Misleading "client scope is not enabled" when a local `var client = ...` is used as a component handle

[bpamiri]

Misleading "client scope is not enabled" when a local var client = ... is used as a component handle

Summary

In a CFWheels app running on Lucee 7, declaring a local variable named client and then calling a method on it produces a confusing runtime error that implicates application configuration rather than the variable name:

function index() {
    var client = paiApiClient();         // a component instance
    var result = client.partInquiry(params.partNumber);  // <-- 500s here
}

lucee.runtime.exp.ExpressionException: client scope is not enabled

The app never touches the client scope — clientManagement is intentionally off. The identifier client in client.partInquiry(...) resolves to the built-in client scope (which precedence-wins over the local var), and with client management disabled, reading it throws. The error message points at app config, so the actual cause (a poorly-chosen local variable name) is very hard to spot.

Why this is worth a CFWheels note

The root cause is Lucee/CFML scope-precedence (so the engine behavior itself isn't CFWheels' to change), but CFWheels developers hit this constantly because:

1. Controllers and models are the natural place to grab a service/component into a local handle, and client, request, form, etc. are tempting names.
2. CFWheels already documents url / form / session / cgi / request / application / cookie as unsafe local-variable identifiers in several places — but client is missing from that list, even though it's the same trap and arguably more confusing (the error names the scope, not the variable).

Requests (any one would help)

1. Docs: add client to the documented list of reserved scope identifiers that must not be used as local/var names (alongside url/form/session/cgi/request/application/cookie).
2. Optional dev-mode diagnostic: when a client-scope error fires while clientManagement is disabled, surface a hint like "identifier 'client' refers to the (disabled) client scope; did you mean a local variable?"

Environment

• CFWheels 4.0 (LuCLI), Lucee 7.0.0.395
• Discovered building a DataPAI feature in the Titan app; workaround was simply renaming the local to apiClient.

Reported from a real migration; happy to provide a minimal repro if useful.

[wheels-bot]

Wheels Bot — Triage

Classified as docs-request.

Docs scope

The reporter asks for client to be added to the documented list of reserved CFML scope identifiers (alongside url, form, session, cgi, request, application, cookie) that should never be used as var / local variable names in controllers, models, or tests. The rule is already captured in agent-facing docs (CLAUDE.md anti-pattern #11 and .ai/wheels/testing/browser-testing.md), but I do not see a user-facing "reserved scope names" / "naming pitfalls" section in web/sites/guides/src/content/docs/v4-0-0/. Write-docs needs to either (a) find or create the right home for this list — likely under basics/controllers-and-actions.mdx or core-concepts/mvc-in-wheels.mdx, or a new short page — and explicitly call out client with the specific Lucee error ("client scope is not enabled") that misleads developers when clientManagement=false. The reporter's optional dev-mode diagnostic request is a separate framework-design ask and is out of scope here.

One adjacent wrinkle worth a heads-up: the v4 testing guides (testing/controller-tests.mdx, testing/integration-tests.mdx, testing/functional-tests.mdx, testing/view-and-form-tests.mdx) currently use var client = $testClient(); as the canonical pattern, which conflicts with this rule. Write-docs should decide whether to rename those examples (e.g. var testClient = $testClient();) as part of this work or leave them for a follow-up.

Confidence: medium

Deliverable is concrete (add client to a reserved-scope list), but the right home page is ambiguous — no existing user-facing page lists reserved scope identifiers — and the scope likely expands to renaming var client in several testing-guide examples for consistency.

<!-- wheels-bot:triage:2833 -->
<!-- wheels-bot:triage-class:docs-request -->
<!-- wheels-bot:docs-confidence:medium -->

[wheels-bot]

Wheels Bot — Docs proposed

Draft PR: #2834

Pages updated:

• web/sites/guides/src/content/docs/v4-0-0/basics/controllers-and-actions.mdx — new "Reserved scope names" section added before "Related guides"
• CHANGELOG.md — one-line [Unreleased] entry

Screenshots needed: none

The new section lists all reserved CFML scope identifiers (client, url, form, session, cgi, request, application, cookie, server, arguments, variables) that must not be used as local variable names. It explains the client collision in detail — including the exact Lucee 7 error message and a wrong/right code example — and includes a caution note that var client = $testClient() in test code hits the same trap.

The testing guide rename (var client → var httpClient across the four testing guide files) is flagged in the PR as a recommended follow-up, kept out of this PR to avoid scope creep.

A human review is required before merge. Reviewer A and Reviewer B will weigh in shortly.