First 15 Minutes tutorial fails. The key [WO] does not exist.

[teleotic]

Describe the bug
Fresh installation of Wheels 4.0.1. Following the "Your First 15 Minutes Tutorial" results in an error on the first page after server start: "The key [WO] does not exist."

Error page indicates the error occurs in the onError function itself:

The Error Occurred in
/home/tim/Projects/hello/public/Application.cfc: line 277
275: }
276:
277: local.requestTimeout = application.wo.$getRequestTimeout() + 30;
278: if (StructKeyExists(application, "wheels") && StructKeyExists(application.wheels, "onErrorRequestTimeout")) {
279: local.requestTimeout = application.wheels.onErrorRequestTimeout;

Commenting out onError to try and figure out what the underlying issue is, got another error related to dependency injection: could not find component or class with name [wheels.Injector].

The Error Occurred in
/home/tim/Projects/hello/public/Application.cfc: line 93
91: function onApplicationStart() {
92: application.env = duplicate(this.env);
93: application.wheelsdi = new wheels.Injector("wheels.Bindings");
94:
95: /* wheels/global object */

To Reproduce

1. Install wheels following tutorial instructions for Linux
2. Follow "Your First 15 minutes" step 1 to create a new Wheels app
3. wheels start
4. Browser loads page with error

Expected behavior
Per tutorial, a welcome page with the message: “Welcome to hello. Your Wheels application is running.”

Desktop (please complete the following information):

• OS: Ubuntu Linux 26.04 LTS
• Browser: Chrome 148.0.7778.167, Firefox 150.0.3
• wheels version 4.0.1
• Lucee Express 7.0.0.395

Additional context
This is my first github bug report. I read the guidelines before writing up this submission, but please let me know if I missed anything.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

cli — see .ai/wheels/testing/onboarding-harness.md for the canonical fresh-install reproduction harness.

The reporter is hitting two stacked failures on a fresh wheels new → wheels start flow with Wheels 4.0.1 on Lucee Express 7.0.0.395:

1. onApplicationStart (Application.cfc line 93) — new wheels.Injector("wheels.Bindings") throws "could not find component or class with name [wheels.Injector]".
2. onError (Application.cfc line 277) — because application.wheelsdi never got assigned, application.wo doesn't exist, so the error handler itself crashes with The key [WO] does not exist.

The second failure is just a symptom of the first: the wheels CFML mapping isn't resolving to a usable vendor/wheels/Injector.cfc during onApplicationStart. Either wheels new isn't populating vendor/wheels/ correctly, the generated this.mappings["/wheels"] path doesn't resolve under Lucee 7's stricter mapping behavior, or the install copy step is dropping files.

Fix sketch

Reproduce locally with bash tools/test-onboarding.sh (90s, mirrors the fresh-VM tutorial path the reporter followed). Investigation targets, in order:

1. cli/lucli/templates/app/public/Application.cfc — the this.mappings["/wheels"] = this.wheelsDir line at the top; verify this.wheelsDir = this.vendorDir & "wheels/" resolves correctly on a freshly-generated app.
2. The wheels new install flow under cli/lucli/ — confirm vendor/wheels/ is fully populated (especially Injector.cfc and Bindings.cfc) after install, not just symlinked or partially copied.
3. The onError fallback path (Application.cfc lines 260–285) should be hardened so that a failed init doesn't cascade into a second crash — at minimum, guard application.wo before dereferencing it on line 277. That's a defensive fix worth doing regardless of root cause.

Confidence: medium

The reproduction is unambiguous from a fresh-install tutorial path, but the root cause spans multiple plausible layers (install flow, template emission, Lucee 7 mapping resolution) so propose-fix will need to reproduce via the onboarding harness before settling on a layer.

<!-- wheels-bot:triage:2773 -->
<!-- wheels-bot:triage-class:bug -->
<!-- wheels-bot:triage-confidence:medium -->

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2774

Spec: vendor/wheels/tests/specs/cli/OnErrorFallbackGuardSpec.cfc — failing → passing
Implementation: cli/lucli/templates/app/public/Application.cfc, public/Application.cfc

Scope note: this is the defensive onError guard the triage comment called out — the cryptic The key [WO] does not exist. cascade is replaced with a minimal HTML page that surfaces the original Injector-init exception. The deeper question of why new wheels.Injector("wheels.Bindings") fails to resolve on a fresh Wheels 4.0.1 install under Lucee Express 7 (mapping resolution? wheels new not populating vendor/wheels/?) is unchanged by this PR and stays open for follow-up via bash tools/test-onboarding.sh.

Heads up: local test execution wasn't possible inside the bot's sandbox (no wheels CLI on PATH, no Docker). The CI compat-matrix on the PR will run the spec across every engine × DB.

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.

[bpamiri]

@teleotic — quick update and an optional ask.

Two fixes for what you hit landed on develop overnight, both shipping in 4.0.2:

• #2776 — the root cause. The Linux .deb/.rpm packages were double-nesting the framework one directory too deep (/opt/wheels/module/vendor/wheels/wheels/Injector.cfc instead of /opt/wheels/module/vendor/wheels/Injector.cfc), so Lucee's /wheels mapping pointed at the wrong place and new wheels.Injector(...) couldn't resolve. Every fresh wheels new install on Ubuntu/Fedora hit it.
• #2774 — defensive guard so onError doesn't cascade into "The key [WO] does not exist." anymore. Future init failures will surface the real exception instead of the cryptic key error you saw.

Both are in 4.0.2-snapshot.1925 on the bleeding-edge channel. Stable 4.0.2 follows once it's validated.

Would you be willing to verify on your Ubuntu 26.04 box before we cut 4.0.2 stable? Totally optional. If you have a few minutes:

# Remove the broken install
sudo apt remove wheels

# Install the bleeding-edge build with the fix
SNAP_TAG=$(curl -fsSL https://api.github.com/repos/wheels-dev/wheels-snapshots/releases \
  | sed -nE 's/.*"tag_name": *"v([^"]+)".*/\1/p' | head -1)
SNAP_FILENAME_VER="${SNAP_TAG//-/.}"
curl -fsSLO "https://github.com/wheels-dev/wheels-snapshots/releases/download/v${SNAP_TAG}/wheels-be_${SNAP_FILENAME_VER}_amd64.deb"
sudo apt install "./wheels-be_${SNAP_FILENAME_VER}_amd64.deb"

# Re-run the tutorial
wheels new hello
cd hello
wheels start
# Open http://localhost:8080

Reply with what you see:

• Welcome page renders (fix confirmed — we'll cut 4.0.2 stable)
• Different error (paste the message)
• Same [WO] error (something's off in the snapshot pipeline)

Thanks for the clean repro in the original report — exact versions, full stack trace. Made the diagnosis straightforward.

[teleotic]

I followed your procedure and the welcome page now renders correctly. Thanks!

[bpamiri]

Thanks for confirming, @teleotic — that's the validation we needed before cutting 4.0.2 stable. Both fixes will ship in that release; you can switch back to the stable channel once it's out (sudo apt remove wheels-be && sudo apt install ./wheels_4.0.2_amd64.deb).

Closing the loop here.