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

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

Install wheels following tutorial instructions for Linux
Follow "Your First 15 minutes" step 1 to create a new Wheels app
wheels start
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 — 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:

onApplicationStart (Application.cfc line 93) — new wheels.Injector("wheels.Bindings") throws "could not find component or class with name [wheels.Injector]".
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:

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.
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.
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 — 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.

Merge branch 'develop' into peter/fix-2773-linux-package-framework-ne…

fix(ci): stop double-nesting framework inside Linux .deb/.rpm packages (

docs(web/guides): correct Linux bleeding-edge install URLs to wheels-…

@teleotic

@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.

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

@teleotic

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.

Release 4.0.2 (#2819)

fix(config): harden onError against Adobe applicationScope teardown (#…

Navigation Menu

Repository navigation

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

Wheels Bot — Triage

Suspected layer

Fix sketch

Confidence: `medium`

Wheels Bot — Fix proposed

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Activity

wheels-bot commented on May 21, 2026

Wheels Bot — Triage

Suspected layer

Fix sketch

Confidence: medium

wheels-bot commented on May 21, 2026

Wheels Bot — Fix proposed

bpamiri commented on May 21, 2026

teleotic commented on May 21, 2026

bpamiri commented on May 21, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Confidence: `medium`