fix(cli): guard application.wo in onError so init failures don't cascade (#2774)

* fix(cli): guard application.wo in onError so init failures don't cascade

When the Wheels Injector fails to load during onApplicationStart (a stale
/wheels mapping under Lucee Express 7 is the symptom users hit on the
"Your First 15 Minutes" tutorial), application.wo is never assigned. The
existing recovery try/catch inside onError swallows a second failure
silently and then unconditionally calls application.wo.$getRequestTimeout(),
which throws "The key [WO] does not exist." and replaces the real
diagnostic with a cryptic cascade.

Add a StructKeyExists(application, "wo") guard right after the recovery
try/catch in cli/lucli/templates/app/public/Application.cfc (the template
behind `wheels new`) and the demo public/Application.cfc. When the global
isn't there, render a minimal HTML error page and return — the user sees
"Wheels failed to initialize" plus the original exception message instead
of the cascade.

Fixes #2773

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* docs(web/guides): note application error fallback and init failure in troubleshooting docs

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(cli): address Reviewer A/B consensus findings (round 1)

- Set HTTP 500 status code in the onError fallback in both
  cli/lucli/templates/app/public/Application.cfc and public/Application.cfc
  so monitoring tools and CDNs don't cache the Wheels-init failure as
  a successful response. Uses a plain struct for cfheader's
  attributeCollection per CLAUDE.md cross-engine invariant #10
  (Adobe CF 2023/2025 reject the arguments scope on built-in tags).
- Document the no-nested-braces assumption behind catchClosePattern in
  vendor/wheels/tests/specs/cli/OnErrorFallbackGuardSpec.cfc so a future
  edit that adds nested braces inside the outer catch knows why the
  silent fallback to scanFrom=1 is the safety net.
- Fix the contradictory recovery steps in the first-15-minutes guide
  (wheels reload requires a running server) at
  web/sites/guides/src/content/docs/v4-0-1-snapshot/start-here/first-15-minutes.mdx.
- Replace the speculative "pre-4.0.2" wording in
  .ai/wheels/troubleshooting/common-errors.md with "4.0.1 or earlier"
  since the fix is still in [Unreleased].

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* chore(web): refresh visual baseline(s) (all)

Manually triggered baseline refresh via
.github/workflows/refresh-visual-baselines.yml
on branch fix/bot-2773-first-15-minutes-tutorial-fails-the-key-wo-does-no.

Run when an intentional content/layout change makes the visual-regression
check fail. The new PNG(s) under web/tests/visual-baselines/ are now the
expected rendering; re-run the failing visual-regression job to flip the
check green.

---------

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: wheels-bot[bot]

.ai/wheels/troubleshooting/common-errors.md

@@ -9,6 +9,26 @@ Frequent issues encountered when developing Wheels applications and their soluti
 - Association syntax has specific Wheels conventions
 - Migration parameter binding can be unreliable
 
+## Startup / Initialization Errors
+
+### "Application Error — Wheels failed to initialize"
+**Error (on-page):**
+```
+Application Error
+Wheels failed to initialize. Check the server log for details.
+<pre>could not find component or class with name [wheels.Injector]</pre>
+```
+
+**Cause:** `onApplicationStart` threw before `application.wo` was assigned — typically because the `/wheels` CFML mapping points to a directory that doesn't contain `Injector.cfc`. The `onError` handler now surfaces the original exception text instead of cascading into "The key [WO] does not exist" (fixed in [#2774](https://github.com/wheels-dev/wheels/pull/2774)).
+
+**Resolution:**
+1. Read the `<pre>` block — it contains the original error (missing class, path mismatch, etc.).
+2. Check the server log for the full stack trace from `onApplicationStart`.
+3. Verify the `/wheels` mapping resolves: on a fresh install, `vendor/wheels/Injector.cfc` must exist. If it doesn't, re-run `wheels new` or copy the framework files manually.
+4. Run `wheels reload` (or stop/start the server) to pick up the corrected mapping.
+
+**Note:** Before the #2774 fix, this failure cascaded into a second `[WO] does not exist` exception that hid the real cause. If you see the old cascade on a version that predates this fix (i.e. 4.0.1 or earlier), the underlying cause is always a failed `onApplicationStart` — see above.
+
 ## Common Association Errors
 
 ### "Missing argument name" in hasMany()

CHANGELOG.md

@@ -18,6 +18,14 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 
 ----
 
+# [Unreleased]
+
+### Fixed
+
+- `onError` in the generated app template and demo `public/Application.cfc` now guards `application.wo` with `StructKeyExists(application, "wo")` after the recovery try/catch. When `new wheels.Injector(...)` fails during `onApplicationStart` (e.g. a stale `/wheels` mapping under Lucee Express 7), the original error is preserved via a minimal HTML fallback instead of cascading into the cryptic "The key [WO] does not exist" exception that hit "Your First 15 Minutes" tutorial users on fresh installs
+
+----
+
 # [4.0.1](https://github.com/wheels-dev/wheels/releases/tag/v4.0.1) => 2026-05-20
 
 > **Wheels 4.0.1** — first patch on the 4.0 line. Hardens Adobe ColdFusion 2023/2025 compatibility (Adobe-specific `cfheader` attributeCollection rejection, `env()` reserved-word parameter, Vite asset-walk array-by-value), fixes the Windows Scoop install regressions (`wheels.cmd` cmd.exe pre-parser, `.zip.sha512` sidecar layout), and adds `viewStyle` framework presets to `paginationNav()` plus plural `mappings` aliases to `package.json`. ~100 PRs since the 4.0.0 GA (2026-05-12).

cli/lucli/templates/app/public/Application.cfc

@@ -274,6 +274,34 @@ component output="false" {
 			// Must never break error handling
 		}
 
+		// If the Wheels global never came up (e.g. the /wheels mapping is
+		// stale or Injector.cfc can't be resolved), the original error is
+		// already lost — fall back to a minimal HTML response rather than
+		// cascading into "The key [WO] does not exist." (issue ##2773).
+		if (!StructKeyExists(application, "wo")) {
+			setting requestTimeout=30;
+			// Surface a real 5xx so monitoring tools and CDNs don't cache this
+			// failure as a successful response. Use a plain struct for
+			// attributeCollection — Adobe CF 2023/2025 reject the `arguments`
+			// scope on built-in tags (CLAUDE.md cross-engine invariant ##10).
+			try {
+				local.statusArgs = {statusCode: 500, statusText: "Internal Server Error"};
+				cfheader(attributeCollection=local.statusArgs);
+			} catch (any headerErr) {
+				// Header may already have been written; the body still renders.
+			}
+			WriteOutput("<h1>Application Error</h1>");
+			WriteOutput("<p>Wheels failed to initialize. Check the server log for details.</p>");
+			try {
+				if (isStruct(arguments.Exception) && StructKeyExists(arguments.Exception, "message")) {
+					WriteOutput("<pre>" & encodeForHTML(arguments.Exception.message) & "</pre>");
+				}
+			} catch (any fallbackErr) {
+				// Last-ditch render must never throw.
+			}
+			return;
+		}
+
 		local.requestTimeout = application.wo.$getRequestTimeout() + 30;
 		if (StructKeyExists(application, "wheels") && StructKeyExists(application.wheels, "onErrorRequestTimeout")) {
 			local.requestTimeout = application.wheels.onErrorRequestTimeout;

public/Application.cfc

@@ -288,6 +288,34 @@ component output="false" {
 			// Must never break error handling
 		}
 
+		// If the Wheels global never came up (e.g. the /wheels mapping is
+		// stale or Injector.cfc can't be resolved), the original error is
+		// already lost — fall back to a minimal HTML response rather than
+		// cascading into "The key [WO] does not exist." (issue ##2773).
+		if (!StructKeyExists(application, "wo")) {
+			setting requestTimeout=30;
+			// Surface a real 5xx so monitoring tools and CDNs don't cache this
+			// failure as a successful response. Use a plain struct for
+			// attributeCollection — Adobe CF 2023/2025 reject the `arguments`
+			// scope on built-in tags (CLAUDE.md cross-engine invariant ##10).
+			try {
+				local.statusArgs = {statusCode: 500, statusText: "Internal Server Error"};
+				cfheader(attributeCollection=local.statusArgs);
+			} catch (any headerErr) {
+				// Header may already have been written; the body still renders.
+			}
+			WriteOutput("<h1>Application Error</h1>");
+			WriteOutput("<p>Wheels failed to initialize. Check the server log for details.</p>");
+			try {
+				if (isStruct(arguments.Exception) && StructKeyExists(arguments.Exception, "message")) {
+					WriteOutput("<pre>" & encodeForHTML(arguments.Exception.message) & "</pre>");
+				}
+			} catch (any fallbackErr) {
+				// Last-ditch render must never throw.
+			}
+			return;
+		}
+
 		// In case the error was caused by a timeout we have to add extra time for error handling.
 		// We have to check if onErrorRequestTimeout exists since errors can be triggered before the application.wheels struct has been created.
 		local.requestTimeout = application.wo.$getRequestTimeout() + 30;

vendor/wheels/tests/specs/cli/OnErrorFallbackGuardSpec.cfc

@@ -0,0 +1,153 @@
+/**
+ * Regression for issue ##2773 — "First 15 Minutes tutorial fails. The key
+ * [WO] does not exist."
+ *
+ * When the Wheels Injector fails to load during onApplicationStart (e.g. a
+ * stale ##wheels mapping under Lucee 7), application.wo is never assigned.
+ * onError then fires for the original Injector failure, swallows a second
+ * failure inside its try/catch, and unconditionally calls
+ * application.wo.$getRequestTimeout() — which throws "The key [WO] does not
+ * exist." and replaces the real diagnostic with a cryptic cascade.
+ *
+ * The defensive fix is in each Application.cfc whose onError uses the
+ * try/catch + DI-init pattern: after the catch, guard application.wo with
+ * StructKeyExists(application, "wo") and short-circuit to a minimal error
+ * response if the global never came up. Without the guard, init failure
+ * cascades and hides the actual root cause from the user.
+ */
+component extends="wheels.WheelsTest" {
+
+	function run() {
+
+		describe("Application.cfc onError fallback hardening (issue ##2773)", () => {
+
+			// expandPath("/wheels") resolves to vendor/wheels via the configured
+			// Lucee mapping; the repo root is two levels above.
+			var repoRoot = expandPath("/wheels/../..");
+			var targets = [
+				"cli/lucli/templates/app/public/Application.cfc",
+				"public/Application.cfc"
+			];
+
+			for (var rel in targets) {
+				// Capture the loop variable so the closure body binds the
+				// current value, not the final iteration's value.
+				(function(relPath) {
+					it("guards application.wo before dereferencing it in onError() in " & relPath, () => {
+						var absolute = repoRoot & "/" & relPath;
+						expect(fileExists(absolute)).toBeTrue("Missing file: " & absolute);
+
+						var raw = fileRead(absolute);
+						var content = $stripCfmlComments(raw);
+
+						// Extract the onError function body so we don't pick up
+						// guards from other handlers (e.g. onAbort) that already
+						// check application.wo.
+						var onErrorMatch = reFindNoCase(
+							"(?s)public\s+void\s+function\s+onError\s*\([^\)]*\)\s*\{",
+							content,
+							1,
+							true
+						);
+						expect(onErrorMatch.len[1] > 0).toBeTrue(
+							relPath & " should declare a public void onError() function."
+						);
+
+						var bodyStart = onErrorMatch.pos[1] + onErrorMatch.len[1];
+						var depth = 1;
+						var bodyEnd = bodyStart;
+						var iEnd = len(content);
+						for (var i = bodyStart; i <= iEnd; i++) {
+							var ch = mid(content, i, 1);
+							if (ch == "{") {
+								depth++;
+							} else if (ch == "}") {
+								depth--;
+								if (depth == 0) {
+									bodyEnd = i - 1;
+									break;
+								}
+							}
+						}
+						var onErrorBody = mid(content, bodyStart, bodyEnd - bodyStart + 1);
+
+						// 1. The cascade-guard must exist.
+						expect(
+							reFindNoCase(
+								"StructKeyExists\s*\(\s*application\s*,\s*[""']wo[""']\s*\)",
+								onErrorBody
+							) > 0
+						).toBeTrue(
+							relPath & " onError() must guard application.wo with "
+							& "StructKeyExists(application, ""wo"") before dereferencing "
+							& "it — without the guard a failed Injector init cascades "
+							& "into ""The key [WO] does not exist."" (issue ##2773)."
+						);
+
+						// 2. The guard must short-circuit before the first
+						//    application.wo.* dereference. Find the position of
+						//    the first such call after the catch block closes,
+						//    and assert the guard appears before it.
+						//
+						// Assumption: the outer catch body has no nested
+						// braces. `[^\}]*` only matches catch bodies whose
+						// contents (after comment stripping) contain no `{`
+						// or `}`. If a future edit introduces a conditional
+						// or nested try inside the outer catch, this regex
+						// will fail to match and `scanFrom` falls back to 1
+						// (top of onErrorBody) — the spec still passes as
+						// long as the guard exists, but the "scan after the
+						// catch" precision is lost. Widen the pattern (e.g.
+						// a brace-counter like the one above) if that
+						// becomes necessary.
+						var catchClosePattern = "catch\s*\(\s*any\s+\w+\s*\)\s*\{[^\}]*\}";
+						var catchMatch = reFindNoCase(catchClosePattern, onErrorBody, 1, true);
+
+						// If the body has a try/catch at the top of onError, the
+						// guard must land between the close of that catch and
+						// the first application.wo.* reference. If it doesn't
+						// (simpler form), the guard still needs to come before
+						// the first application.wo.* reference.
+						var scanFrom = (catchMatch.pos[1] > 0)
+							? (catchMatch.pos[1] + catchMatch.len[1])
+							: 1;
+						var tail = mid(onErrorBody, scanFrom, len(onErrorBody) - scanFrom + 1);
+
+						var derefPos = reFindNoCase("application\.wo\.", tail);
+						var guardPos = reFindNoCase(
+							"StructKeyExists\s*\(\s*application\s*,\s*[""']wo[""']\s*\)",
+							tail
+						);
+
+						if (derefPos > 0) {
+							expect(guardPos > 0 && guardPos < derefPos).toBeTrue(
+								relPath & " onError() dereferences application.wo "
+								& "after the recovery try/catch without first "
+								& "guarding it. The guard must appear before any "
+								& "application.wo.* call so a failed Injector "
+								& "init can short-circuit cleanly (issue ##2773)."
+							);
+						}
+					});
+				})(rel);
+			}
+
+		});
+
+	}
+
+	/**
+	 * Strip CFML tag, block, and line comments before scanning. Mirrors
+	 * the helpers under cli/lucli/services (Analysis.cfc, Doctor.cfc) so a
+	 * commented-out access pattern doesn't pollute the structural check
+	 * (CLAUDE.md anti-pattern ##14).
+	 */
+	private string function $stripCfmlComments(required string source) {
+		var stripped = arguments.source;
+		stripped = reReplace(stripped, "<!---[\s\S]*?--->", "", "all");
+		stripped = reReplace(stripped, "/\*[\s\S]*?\*/", "", "all");
+		stripped = reReplace(stripped, "(?m)//[^\n]*", "", "all");
+		return stripped;
+	}
+
+}

web/sites/guides/src/content/docs/v4-0-1-snapshot/start-here/first-15-minutes.mdx

@@ -47,6 +47,10 @@ You'll see log lines ending with something like `Server started successfully`. O
 
 The dev server stays running in the background. Leave the terminal open.
 
+<Aside type="caution" title="Seeing an Application Error page instead?">
+  If the browser shows `Application Error — Wheels failed to initialize` rather than the welcome page, the error message on screen includes the underlying cause. Check the server log for the full stack trace. The most common cause on a fresh install is a stale `/wheels` CFML mapping. While the server is running, try `wheels reload` to pick up the corrected mapping. If that does not clear it, stop and restart the server. The server log will point to the specific file that failed to load.
+</Aside>
+
 ## 3. Add a page (5 min)
 
 <Steps>