Add Known Issue page for CF2023 Update 25 startup failure with FusionReactor

docs/Troubleshooting/Known-Issues/CF2023-Update-25-Startup-Failure.md

@@ -0,0 +1,121 @@
+# ColdFusion 2023 Update 25 prevents startup with FusionReactor on Windows
+
+After applying ColdFusion 2023 Update 25 on Windows, ColdFusion may fail to start while the FusionReactor Java agent is configured in `jvm.config`.
+
+This is caused by a change in ColdFusion 2023 Update 25 and is not a defect in FusionReactor. Any product that loads the Java instrumentation library can trigger the same failure. We are working with Adobe towards a permanent fix.
+
+!!! info "Affected platforms"
+    Only Windows installations are known to be affected. Linux and container installations are not currently known to be affected.
+
+!!! tip "If you have not yet applied Update 25"
+    Update 25 includes security-related library upgrades, so we would not recommend skipping it. Plan to apply one of the workarounds below alongside the update rather than deferring the update itself.
+
+## Symptoms
+
+When ColdFusion is started as a Windows service, the service terminates and the System log in Event Viewer records:
+
+```
+The ColdFusion 2023 Application Server service terminated with the following service-specific error:
+The system cannot find the file specified.
+```
+
+Neither the ColdFusion logs nor the Windows Event logs explain the cause. To see the underlying error, stop the ColdFusion service and start ColdFusion from a command prompt using `C:\ColdFusion2023\cfusion\bin\cfstart.bat`:
+
+```
+Error occurred during initialization of VM
+Could not find agent library instrument on the library path, with error: Can't find dependent libraries
+Module java.instrument may be missing from runtime image.
+```
+
+Removing the `-javaagent` and `-agentpath` arguments from `jvm.config` allows ColdFusion to start. This confirms the diagnosis but is not a solution, as it leaves the server unmonitored. Use one of the workarounds below instead.
+
+## Cause
+
+At startup, ColdFusion builds a PATH for its own process. This is separate from the Windows system PATH and is used only by ColdFusion. It begins with the system PATH and then appends several ColdFusion directories, including the `bin` folder beneath the Java home that ColdFusion is configured to use.
+
+As of Update 25 on Windows, that process PATH is limited to 260 characters. On servers where the system PATH is already long, the appended entries are cut off before the end, so the Java `bin` folder is missing. The Java agent cannot then be loaded, and ColdFusion fails to start.
+
+## Workarounds
+
+Two workarounds are available. Either should work, so choose whichever suits your environment.
+
+!!! warning "Before you apply either workaround"
+    The system PATH change is tied to one specific Java folder and affects every application on the server. If you later change the Java version ColdFusion uses, the entry needs updating to match.
+
+    The registry change is not visible in any ColdFusion configuration file, and it will break `cfexecute` calls that run programs by name rather than by full path.
+
+    Record which workaround you applied and on which servers, so it can be removed once Adobe ships a fix.
+
+### Workaround 1: place the Java bin directory first in the system PATH
+
+Adobe has advised placing the Java `bin` directory at the very start of the system PATH. Adding it at the end has no effect, because the end of the PATH is the part that gets truncated.
+
+Keep the FusionReactor `-javaagent` argument in `jvm.config`, then:
+
+1. Note the `java.home` value in `jvm.config`, found in the same `bin` folder as `cfstart.bat`, for example `C:\Program Files\Java\jdk-17.0.6`.
+
+2. To test without changing the system, stop the ColdFusion service, then open a new Command Prompt as Administrator and run:
+
+    ```
+    set "PATH=<java.home>\bin;%PATH%"
+    cd /d C:\ColdFusion2023\cfusion\bin
+    cfstart.bat
+    ```
+
+3. To apply the change permanently, go to **System Properties > Environment Variables > System variables > Path > New**, add `<java.home>\bin`, then use **Move Up** until it is the first entry in the list.
+
+4. Reboot the machine. The Windows service only picks up system PATH changes after a reboot. Then start the **ColdFusion 2023 Application Server** service.
+
+### Workaround 2: set the PATH for the ColdFusion service only
+
+Charlie Arehart has published an alternative that changes the PATH for ColdFusion only and leaves the system PATH untouched. It sets the PATH that ColdFusion sees to a short placeholder string, so that ColdFusion's own appended directories fit within the limit. The value cannot be empty, as ColdFusion only appends its directories when it finds a non-empty PATH.
+
+**When starting ColdFusion from the command line:**
+
+1. Stop the ColdFusion service.
+2. In the command prompt, run `path=xx`.
+3. Start ColdFusion with `C:\ColdFusion2023\cfusion\bin\cfstart.bat`.
+
+This applies only to that command prompt window.
+
+**When running ColdFusion as a Windows service:**
+
+1. Open `regedit` and go to `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ColdFusion 2023 Application Server`.
+2. Create a new multi-string value (`REG_MULTI_SZ`) named `Environment`. If an `Environment` value already exists, edit it and add `path=xx` as a new line rather than creating a second value.
+3. Enter `path=xx` on a single line. If regedit warns about empty strings, click OK.
+4. Start the ColdFusion 2023 Application Server service.
+
+The same change can be made from an elevated command prompt:
+
+```
+reg add "HKLM\SYSTEM\CurrentControlSet\Services\ColdFusion 2023 Application Server" /v Environment /t REG_MULTI_SZ /d "path=xx"
+```
+
+!!! note "Editing the registry"
+    Back up the registry key before making changes. Note that the command above overwrites any existing `Environment` value, so check for one first.
+
+Full background and root cause analysis are available in Charlie's post, [Solving a new problem as of CF2023 update 25 that can cause CF to not start](https://www.carehart.org/blog/2026/9/29/solving_new_cf2023_update_25_startup_problem).
+
+## Multiple ColdFusion instances
+
+Each ColdFusion instance runs as its own Windows service and needs the same change applied individually. To list the services on a server, run:
+
+```
+Get-Service *ColdFusion*
+```
+
+For Workaround 2, each service has its own registry key named after that service, so the `Environment` value must be added to each one.
+
+## Reverting the workaround
+
+Once Adobe releases a fix, remove whichever workaround you applied.
+
+**Workaround 1:** go to **System Properties > Environment Variables > System variables > Path**, select the `<java.home>\bin` entry you added, and remove it. Reboot the machine, then start the ColdFusion service.
+
+**Workaround 2:** stop the ColdFusion service, open `regedit` and go to the service key, then delete the `Environment` value. If you added `path=xx` to an existing `Environment` value, remove only that line and leave the rest in place. Start the service again.
+
+## Status
+
+A permanent fix needs to come from Adobe. The issue is tracked under [CF-4234454](https://tracker.adobe.com/#/view/CF-4234454), and this page will be updated as the position changes.
+
+If you are affected and neither workaround resolves the problem, contact [support@fusion-reactor.com](mailto:support@fusion-reactor.com) with your ColdFusion version and update level, your FusionReactor version, and the output of `cfstart.bat` run from a command prompt.

mkdocs.yml

@@ -133,6 +133,7 @@ nav:
            - Troubleshooting/Cloned-FusionReactor-Instances.md
            - Troubleshooting/Debugger-will-not-start-without-Glibc.md
            - Troubleshooting/Known-Issues/JVM-crash-JDK-11.md
+           - Troubleshooting/Known-Issues/CF2023-Update-25-Startup-Failure.md
            - Troubleshooting/Known-Issues/System-Metrics-unavailable-in-Locked-down-ColdFusion.md
            - Troubleshooting/Requests-from-Adobe-PMT-tracked-in-FusionReactor.md
            - Troubleshooting/Adding-FR-Error-Stack-Trace-On-CFCatch-CFOnError.md