config/environment.cfm needs env() helper guidance — mirrors the reloadPassword bug fixed in #2637

[bpamiri]

Severity: docs — affects every 3.x app that sources environment from .env. Real-world symptom: production VMs send environment=development to Sentry / debug bar / get(\"environment\").

Surfaced by: titan Phase 2.1 (Wheels 4.0 upgrade), 2026-05-15. Same root-cause as #2631 / #2637 (reloadPassword via .env).

Description

Titan's config/environment.cfm (and presumably the 4.0 starter-app template too) currently reads environment from .env like:

set(environment=application.env.environment);

The application.env.<key> chain isn't always populated before config/environment.cfm runs (depends on loadEnvFile() timing in public/Application.cfc). The result: even when .env has environment=production, the runtime sees environment=\"\" or stale value, and set(environment=...) resolves wrong.

In the titan case, this manifested as production VMs reporting environment=development in Sentry despite Ansible rendering .env with environment=production.

Fix shape (mirroring #2637)

Update upgrade guide section 4 and the 4.0 starter-app template's config/environment.cfm to use:

set(environment=env(\"environment\", \"production\"));

env() (introduced in 4.0 per #1985) handles the load-order issue and provides a safe default. Importantly: the default should be \"production\", not \"development\" — failing safe means a missing key resolves to prod, not dev.

Why this matters for v4.0.1

Every 3.x app that uses .env-driven environment (which is most) will silently emit wrong environment tags everywhere they're consumed. Sentry dashboards, error filters, debug-bar visibility, conditional behavior — all wrong.

Suggested

• Update web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx (or equivalent) under item 4
• Update cli/lucli/templates/app/config/environment.cfm in the starter-app scaffold
• Optionally add this case to wheels upgrade check's breaker scanner

cc @bpamiri

[wheels-bot]

Wheels Bot — Triage

Classified as docs-request.

Docs scope

Mirror the pattern established by #2637 (which fixed item 4 of the upgrade guide for reloadPassword). Two upgrade guide pages need item 4 updated to recommend set(environment=env("environment", "production")) instead of reading application.env.environment directly, calling out the load-order issue and the deliberate "production" default for fail-safe behavior:

• web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx
• web/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/3x-to-4x.mdx

The starter-app template at cli/lucli/templates/app/config/environment.cfm should also be updated to use the env() helper so newly scaffolded apps ship with the correct pattern. The optional wheels upgrade check scanner enhancement is out of scope for the docs PR — it can be split into a follow-up issue.

Confidence: high

The gap is concrete (specific item in two known pages plus one template file), the path is unambiguous (direct mirror of the merged #2637 fix), and the work is mechanical translation rather than a design decision.

<!-- wheels-bot:triage:2709 -->
<!-- wheels-bot:triage-class:docs-request -->
<!-- wheels-bot:docs-confidence:high -->

[wheels-bot]

Wheels Bot — Docs proposed

Draft PR: #2720

Pages updated:

• web/sites/guides/src/content/docs/v4-0-0/upgrading/3x-to-4x.mdx — item 4 extended with config/environment.cfm load-order gap sub-section + Common issues entry
• web/sites/guides/src/content/docs/v4-0-1-snapshot/upgrading/3x-to-4x.mdx — same

Screenshots needed: none

Note: the starter-app template at cli/lucli/templates/app/config/environment.cfm is out of scope for the docs stage. A follow-up code PR should update it so newly scaffolded apps ship with set(environment=env("environment", "production")).

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