Routing: inside .namespace("foo"), redundant to="foo/controller##action" produces opaque Foocontroller lookup; should reject or strip the prefix

[bpamiri]

Summary

Inside a .namespace("foo") block, the to= argument of a route gets concatenated with the namespace name in a confusing way: writing the (intuitive but redundant) to="foo/controller##action" produces a lookup for a controller class literally named Foocontroller instead of Controller under the foo package. The correct form is just to="controller##action" — the namespace adds the package prefix automatically — but the failure mode when you get it wrong is opaque.

Repro

// config/routes.cfm — WRONG (matches the namespace prefix redundantly)
mapper()
    .namespace("datapai")
        .get(name="datapaiDashboard", pattern="dashboard", to="datapai/dashboard##index")
    .end()
.end();

Then GET /datapai/dashboard produces:

Wheels.ViewNotFound — Could not find the view page for the `index` action in the `datapai.Datapaidashboard` controller.

Looked for the view at: app/views/datapai/datapaidashboard/index.cfm

The error is misleading. Wheels concatenated the namespace (datapai) with the (already-prefixed) controller path (datapai/dashboard) to form a class name Datapaidashboard — lowercase concatenation with the first letter capitalized. The user, having written datapai/dashboard expecting an app/controllers/datapai/Dashboard.cfc file, can't find the source of the bizarre Datapaidashboard name in the error.

The fix is to drop the redundant prefix:

// config/routes.cfm — CORRECT
mapper()
    .namespace("datapai")
        .get(name="datapaiDashboard", pattern="dashboard", to="dashboard##index")
    .end()
.end();

Now Wheels routes /datapai/dashboard → app/controllers/datapai/Dashboard.cfc#index as expected.

Why this happens

In vendor/wheels/mapper/scoping.cfc:42-49, the scope() function combines the parent scope's path and package with the current scope's, which is correct. But when a route is later registered with to="datapai/dashboard##index", the slash separator in the to= string is interpreted as a controller-path component and concatenated with the namespace's package, yielding datapai/datapai/dashboard → flattened to Datapaidashboard for the class name and datapai/datapaidashboard for the view directory.

There's no obvious place in the codebase where this concatenation is documented or guarded.

Impact

This is a foot-gun for anyone writing namespace routes. The plain to="dashboard##index" form looks underspecified ("but what namespace is this in?") and the redundant to="datapai/dashboard##index" looks defensively correct — until it isn't. The error message gives no hint that the namespace + to= interaction is the cause.

We hit this exactly once during the DataPAI Phase 0 build. Diagnosis required reading both scoping.cfc and the resulting Wheels.ViewNotFound error several times before realizing the issue. The fix is a one-line route change once you know what's wrong, but the diagnosis took ~30 min.

Suggested fixes (any of)

1. Reject the redundant form at route-registration time. Inside a .namespace("foo") scope, if a to= starts with the namespace's name followed by /, throw a routing-config error at startup with a clear message:

   Route inside .namespace("foo") should use to="bar##action", not to="foo/bar##action" — the namespace prefix is added automatically. (got: to="foo/bar##action")

2. Strip the redundant prefix automatically and emit a warning. Less strict than (1) but maintains backward compatibility for anyone whose routes currently work despite the redundant form.

3. Document the interaction clearly in guides.wheels.dev/v4-0-0/routing/. The current docs explain .namespace() and to= separately but don't show their interaction or the "no redundant prefix" rule.

4. Improve the ViewNotFound error message to include "Route registered as to='X' inside .namespace('Y')" so the user can trace it back to the route definition rather than the symptom.

Repo / version

• Wheels Core: 4.0.0-SNAPSHOT+1779
• File: vendor/wheels/mapper/scoping.cfc:42-49 (path/package combine logic)
• Likely also in the route-registration path that parses to="controller##action" — needs investigation by someone with deeper Wheels routing knowledge to confirm the exact line.

Where found

Diagnosed during the DataPAI Phase 0 build in Titan when adding /datapai/* routes to land internal SSO users on a separate portal. The wrong form was committed first (taken literally from a draft plan that pre-dated familiarity with the Mapper); a follow-up commit on the same branch fixed it. See paiindustries/titan PR #3337 commit ad61a86cd for the corrected routes.cfm.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

Suspected layer

router — see vendor/wheels/mapper/scoping.cfc and vendor/wheels/mapper/matching.cfc; CLAUDE.md § "Routing Quick Reference" for canonical patterns.

Fix sketch

The problem path is in vendor/wheels/mapper/matching.cfc::$match lines 296-310: when inside .namespace("foo"), the scope-stack already supplies package = "foo" (lines 297-302); the to="foo/dashboard##index" string is then split at ## (line 307) yielding arguments.controller = "foo/dashboard"; lines 377-378 join them into "foo.foo/dashboard", which downstream gets flattened to the Foodashboard-style class name. The fix likely lives in matching.cfc, immediately after the to split (line 309) — detect when arguments.controller begins with the scope's package segment followed by / and either reject at registration time (option 1 in the issue), auto-strip with a warning (option 2), or — at minimum — surface the namespace + to interaction in the downstream Wheels.ViewNotFound/Wheels.ControllerNotFound error (option 4). Picking among 1/2/4 is a small design call; the simplest defensible fix is option 1 (throw Wheels.MapperArgumentInvalid at startup with a message that names both the namespace and the offending to=), with option 3 (docs note in web/sites/guides/src/content/docs/v4-0-0/routing/) as a follow-up.

Confidence: medium

The report is precise and the failing path is mechanically clear, but the fix requires picking among four reasonable approaches (reject vs strip-with-warning vs error-message improvement vs docs-only), so propose-fix should commit to an approach explicitly rather than treat it as a one-line mechanical change.

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

[bpamiri]

Followup data point from continuing to use the fix in production code: this quirk has a route-name dimension in addition to the to= dimension above.

Inside .namespace("datapai"), a route declared as:

.get(name="datapaiDashboard", pattern="dashboard", to="dashboard##index")

…registers with the composed name datapaiDatapaiDashboard, not datapaiDashboard. The composition logic in vendor/wheels/mapper/matching.cfc:382-401 builds [$scopeName(), $collection(), local.name] then joins/capitalizes:

local.nameStruct = [$scopeName(), $collection(), local.name];  // → ["datapai", "", "datapaiDashboard"]
local.name = ArrayToList(local.nameStruct);                      // → "datapai,,datapaiDashboard"
local.name = ReReplace(local.name, "^,+|,+$", "", "all");
local.name = ReReplace(local.name, ",+(\w)", "\U\1", "all");     // → "datapaiDatapaiDashboard"
local.name = ReReplace(local.name, ",", "", "all");

So urlFor(route="datapaiDashboard") fails with Could not find the 'datapaiDashboard' route. — the registered name is datapaiDatapaiDashboard.

The fix is to drop the redundant prefix in the route declaration: name="dashboard" inside .namespace("datapai") composes correctly to datapaiDashboard. That's the same "don't prefix what the namespace will prefix for you" rule as the to= issue.

So the original suggested fixes still apply, but the error-at-registration approach (fix #1) should also reject name="<scopeName>..." in addition to rejecting to="<scopeName>/...". Otherwise the user gets urlFor() errors at view-render time instead of an early routing-config error.

Verified empirically by dumping application.wheels.mapper.getRoutes() from a transient spec — pattern: "/datapai/dashboard" registered under name: "datapaiDatapaiDashboard".

Fix in our app: paiindustries/titan PR #3337 commit c9562b870.

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2794

Spec: vendor/wheels/tests/specs/mapper/MatchingSpec.cfc — 6 new specs (4 reject-cases + 2 accept-cases) — failing → passing
Implementation: vendor/wheels/mapper/matching.cfc ($match(), right after the to= split — guard throws Wheels.MapperArgumentInvalid when the parsed controller starts with the scope's package in slash form)

Picked option 1 from the triage menu ("Reject the redundant form at route-registration time"). Surfaces at app boot rather than at first request, and the error message names both the namespace and the offending to= value with the corrected shorter form, so users can find the bad route definition instead of chasing the Wheels.ViewNotFound symptom.

Verified locally: wheels.tests.specs.mapper 76/76, wheels.tests.specs.dispatch 96/96, wheels.tests.specs.controller 423/423 on Lucee 7 + SQLite. No regressions.

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.