Reload: bare ?reload=true does NOT re-include app/global/*.cfm files — full re-init requires ?reload=true&password=<admin>

[bpamiri]

Summary

Hitting a URL with ?reload=true does NOT re-evaluate <cfinclude> directives in app/global/functions.cfm (or any included file like app/global/datapai/helpers.cfm). New functions added to those included files are invisible until a full applicationStop() runs — which is only triggered by ?reload=true&password=<admin> (where <admin> is the admin.password value from lucee.json).

Net effect: when developing new helper functions, the obvious developer reflex (?reload=true) lies. The page renders without error, but the new helper is still undefined. Looks like Lucee/Wheels just isn't picking it up, but actually the reload silently skipped the re-include step.

Repro

1. Add a new function to a project's global helpers:

// app/global/datapai/helpers.cfm (the file is included from app/global/functions.cfm)
<cfscript>
function newHelperJustAdded() {
    return "I am brand new";
}
</cfscript>

2. Hit the dev server with ?reload=true:

curl -s "http://localhost:60050/?reload=true" -o /dev/null -w "HTTP %{http_code}\n"
# HTTP 302

3. Try to use the new helper in a controller or view:

// app/controllers/Smoke.cfc
function index() {
    writeOutput(newHelperJustAdded());  // throws: function 'newHelperJustAdded' is not defined
    abort;
}

4. Now hit with ?reload=true&password=titan4dev (or whatever your Lucee admin password is, from lucee.json):

curl -s "http://localhost:60050/?reload=true&password=titan4dev" -o /dev/null -w "HTTP %{http_code}\n"
# HTTP 302

5. Re-try step 3 — the helper now resolves correctly.

The difference: ?reload=true&password=... triggers applicationStop(), forcing the application scope to be torn down and onApplicationStart to re-fire, which re-evaluates the app/global/functions.cfm include chain. Bare ?reload=true runs a softer reload that re-loads SOME settings/routes but doesn't re-include global function files.

Impact

This caused real iteration friction during the DataPAI Phase 0 build. Every time we added a new helper function and tried to test it, the first ?reload=true request would appear successful but the function was missing. Spending several minutes debugging "why isn't my helper working" before remembering to use the password form is a common pattern.

Documentation in the dev guides mentions ?reload=true as the standard reload mechanism but doesn't flag this limitation. Users discover it through frustration.

Why this happens (my hypothesis)

Wheels' ?reload=true handling (in vendor/wheels/events/onapplicationstart.cfc and the request lifecycle) re-runs a subset of init code — it re-loads application.wheels config, re-fires routes.cfm to rebuild the route table, etc. But it does NOT re-evaluate app/global/functions.cfm, which is <cfinclude>'d into Global.cfc at the time Global.cfc itself was first instantiated. Including a CFM file at component construction time is a one-shot operation; the included symbols are merged into the component's variables scope and stay there until the component is re-instantiated.

A ?reload=true doesn't tear down application.wo (the Global.cfc instance), so the included symbols remain stale.

?reload=true&password=<admin> calls Lucee's applicationStop() (gated by the admin password as a safety mechanism). This tears down the application scope completely, forcing onApplicationStart to re-fire which re-instantiates application.wo (Global.cfc) which re-evaluates the <cfinclude> chain.

Suggested fixes (any of)

1. Make ?reload=true actually re-include app/global/*.cfm by either (a) re-instantiating Global.cfc as part of the reload pipeline, or (b) tracking the included files and re-evaluating them explicitly. Either way, the behavior matches the developer's mental model: "reload means everything in the app is fresh".

2. Document the limitation prominently in guides.wheels.dev/v4-0-0/configuration-and-defaults/. Show side-by-side what ?reload=true does vs. ?reload=true&password=<admin> so users know which one to reach for.

3. Print a warning during dev runs when a request notices the app/global/*.cfm files have a newer mtime than the application's load time. Something like "Your app/global files have changed since startup; run ?reload=true&password=<admin> for a full reload." Only in dev, only once per file-change-detection.

4. Add a wheels reload CLI command that hits the password-reload URL with the password from lucee.json. Skips the muscle-memory issue entirely.

Repo / version

• Wheels Core: 4.0.0-SNAPSHOT+1779
• File: vendor/wheels/events/onapplicationstart.cfc (where the reload-with-password branching lives — line ~417 is the $location redirect post-reload, but the reload-decision logic is earlier in the file)

Where found

Surfaced repeatedly during the DataPAI Phase 0 build in Titan. We added ~10 helpers across 2 helper-include files; each helper's first invocation required learning (or remembering) to use the password reload. The CLAUDE.md gotcha list captured at the end of Phase 0 (paiindustries/titan PR #3337 commit e3ab806bb) flags this as one of 9 things to know about Wheels' dev iteration model.

[wheels-bot]

Wheels Bot — Triage

Classified as framework-design (API/feature design question).
Cross-framework research will follow shortly — Rails, Laravel, Django,
and other modern frameworks will be consulted before any path forward
is proposed.

[wheels-bot]

Wheels Bot — Cross-Framework Research

Question

Wheels' bare ?reload=true re-runs config + routes but does NOT re-evaluate the <cfinclude> of app/global/functions.cfm. Symbols included into Global.cfc at construction time stay frozen until application.wo is re-instantiated, which only happens via the password-gated path that calls applicationStop(). Developers adding a new helper hit a silent-failure cliff: the page renders, the helper is undefined, nothing names the cause.

How other frameworks handle this

Framework	Naming	Surface	Trade-offs	Edge cases
Rails (Zeitwerk)	enable_reloading, autoload_paths, reload!, to_prepare	ActionDispatch::Executor runs FileUpdateChecker per request; Zeitwerk unloads + re-lazy-loads constants when mtimes change	Zero dev command; polling scales with autoload_paths	config/initializers/* + Gemfile need restart; tmp/restart.txt is the puma trigger file
Laravel	composer dump-autoload, optimize:clear, octane:reload, octane:start --watch	PHP per-request reboot picks up edits for free; new files need dump-autoload. Octane needs octane:reload or --watch (chokidar)	Free reload is the upside of fork-everything	config:cache freezes .env; Octane singletons pin stale state
Django	runserver, --noreload, autoreload_started/file_changed signals, watch_dir(path, glob)	Parent StatReloader (or WatchmanReloader) SIGTERMs child on mtime change; child re-execs	Full process restart drops in-flight requests	New files in unimported dirs unwatched until imported; production WSGI never uses this
Phoenix	code_reloader: true, reloadable_apps, reloadable_compilers, Phoenix.CodeReloader plug	Per-request plug stats watched paths and mix-compiles changed modules; BEAM hot code load swaps modules without restart	Zero command; serialized recompile gate adds latency	config/*.exs + supervision tree need mix restart; live-reload is a separate plug
Spring Boot DevTools	spring-boot-devtools, restart.trigger-file, restart.poll-interval	Two-classloader trick: base loader (deps) stays warm, restart loader (code) recreated — 5–10x faster than JVM cold start	Still a full context rebuild; needs IDE recompile	Static fields/singletons in base loader survive restart; trigger-file gates manual restarts
FastAPI/uvicorn (+1)	--reload, --reload-dir, --reload-include, --reload-delay	WatchFiles parent SIGTERMs child + respawns; picked as +1 because uvicorn is the framework whose request lifecycle most resembles Wheels (one process, no BEAM, no classloader trick)	Full process restart; cold-start cost per save	.env and templates need explicit --reload-include

Dominant pattern

Every modern framework treats automatic, no-friction reload in development as the default. They split on granularity — Phoenix BEAM swap, Rails constant unload, Spring classloader restart, Django/uvicorn process respawn — but agree on three things: (a) the developer types no command for normal edits, (b) the mechanism is gated to development environments, (c) there is an opt-in watch-list concept so apps extend what counts as reloadable. The password-protected applicationStop() Wheels exposes today maps cleanly to Spring trigger-file: a deliberate harder reload for cases the safe-by-default cannot handle. The gap is not the password path; it is the safe-by-default reload being too narrow.

Recommended path for Wheels

CFML is closer to Rails than Phoenix: no BEAM, no classloader trick, but <cfinclude> can be re-evaluated cheaply against the existing component — no JVM cold-start tax. Adopt the Rails/Phoenix per-request mtime-check pattern on the existing ?reload=true path so muscle memory keeps working. Keep the password path as the explicit applicationStop() escape hatch (analogous to Spring trigger-file). Add a wheels reload CLI verb so devs do not have to remember the password URL form.

// vendor/wheels/Global.cfc — new PUBLIC helpers with dollar-prefix
// (anti-pattern 7: private mixins are not integrated by $integrateComponents).

public struct function $snapshotGlobalIncludes() {
    var snapshot = StructNew();
    var dir = ExpandPath("/app/global");
    if (!DirectoryExists(dir)) return snapshot;
    var files = DirectoryList(dir, true, "query", "*.cfm");
    cfloop(query="files") {
        snapshot[files.directory & "/" & files.name] = files.dateLastModified;
    }
    return snapshot;
}

public boolean function $globalIncludesChanged() {
    if (!StructKeyExists(application.$wheels, "globalIncludesSnapshot")) return false;
    var current = $snapshotGlobalIncludes();
    var prior = application.$wheels.globalIncludesSnapshot;
    for (var key in current)
        if (!StructKeyExists(prior, key) OR prior[key] NEQ current[key]) return true;
    for (var key in prior)
        if (!StructKeyExists(current, key)) return true;
    return false;
}

public void function $reincludeGlobals() {
    include "/app/global/functions.cfm";
    application.$wheels.globalIncludesSnapshot = $snapshotGlobalIncludes();
}

// onapplicationstart.cfc — in the ?reload=true branch, before routes/config re-init:
if (
    application.$wheels.environment EQ "development"
    AND application.$wheels.reloadOnGlobalChange
    AND $globalIncludesChanged()
) {
    $reincludeGlobals();
}

// config/settings.cfm — new dev-only default:
set(reloadOnGlobalChange=true);

// cli/lucli/Module.cfc — new MCP/CLI verb
public any function reload(boolean hard = false) {
    var adminPassword = $resolveLuceeAdminPassword();
    var reloadUrl = "http://localhost:" & $detectDevPort() & "/?reload=true";
    // anti-pattern 11: locals are adminPassword/reloadUrl, NOT password/url
    // — those would shadow URL.password / URL scope.
    if (arguments.hard AND Len(adminPassword)) reloadUrl &= "&password=" & EncodeForURL(adminPassword);
    return $httpGet(reloadUrl);
}

Lives in: vendor/wheels/events/onapplicationstart.cfc, vendor/wheels/Global.cfc, cli/lucli/Module.cfc, config/settings.cfm. Composes with existing set(reloadPassword=...), ?reload=<env> switch, and the failed-password rate limiter — all unchanged.

Cross-engine notes

DirectoryList(returnType="query"), GetFileInfo(), and include re-evaluation work on Lucee 5/6/7, Adobe CF 2018/2021/2023/2025, and BoxLang. The sketch avoids: obj.map() (cross-engine invariant 1), closures-as-named-constructor-args (5, catastrophic on Adobe CF), attributeCollection=arguments on tags (10), private mixin methods (7), and reserved scope shadowing (11 — never names a local url or password). Empty-snapshot first-request case returns false (12 empty-input discipline).

Open questions

• Extend the mtime check to app/controllers/ and app/models/, or keep it scoped to app/global/*.cfm? Wheels already reloads those per-request when their cache initialization flags are off, so scoping minimal seems right for v1.
• Poll every request or only when ?reload=true is present? Proposal above is the latter (no overhead for users not hitting reload).
• Should wheels reload --hard always be the default in development, sidestepping this class of bug at the cost of slower reloads? Worth a separate human discussion.

Confidence: high

Dominant pattern is clear (auto-reload in dev, no command), Wheels existing ?reload=true has the right shape to extend, the CFML sketch respects every relevant anti-pattern (1, 2, 7, 10, 11, 12), and no cross-engine concerns surfaced. No new infrastructure required.

Sources

• Rails autoload: https://guides.rubyonrails.org/autoloading_and_reloading_constants.html
• Rails file watcher: https://api.rubyonrails.org/classes/ActiveSupport/FileUpdateChecker.html
• Laravel helpers: https://laravel.com/docs/11.x/helpers
• Laravel Octane: https://laravel.com/docs/11.x/octane
• Django admin: https://docs.djangoproject.com/en/5.0/ref/django-admin/
• Django autoreload: https://github.com/django/django/blob/main/django/utils/autoreload.py
• Phoenix CodeReloader: https://hexdocs.pm/phoenix/Phoenix.CodeReloader.html
• Phoenix source: https://github.com/phoenixframework/phoenix/blob/main/lib/phoenix/code_reloader.ex
• Spring DevTools: https://docs.spring.io/spring-boot/reference/using/devtools.html
• uvicorn supervisor: https://github.com/encode/uvicorn/blob/master/uvicorn/supervisors/watchfilesreload.py

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #2795

Spec: vendor/wheels/tests/specs/global/reloadGlobalsSpec.cfc — failing (7 errors: Component [wheels.Global] has no function with name [$snapshotGlobalIncludes] etc.) → passing (7/7 green, full core suite 3698 / 0 / 0)

Implementation:

• vendor/wheels/Global.cfc — three new public $-prefixed helpers
• vendor/wheels/events/init/orm.cfm — reloadOnGlobalChange default (true in dev, false elsewhere)
• vendor/wheels/events/onapplicationstart.cfc — capture initial snapshot
• vendor/wheels/events/EventMethods.cfc — per-request soft-reload check on bare ?reload=true

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.