Intermittent 'Can't cast Complex Object Type Struct to String' on first POST /signup after cold reload

[bpamiri]

Symptom

Reported during the 2026-05-01 fresh-VM tutorial run (chapter 6, "Test 6a manually"). The very first POST to /signup after wheels reload raised:

Lucee 7.0.0.395 Error (expression)
Can't cast Complex Object Type Struct to String
/Users/peter/ws/blog/app/models/User.cfc: line 13
   13:  this.email = Trim(LCase(this.email));

What's confusing about it

The error implicates LCase(this.email), suggesting this.email is a struct rather than a string. But:

• The submitted form body is plain key=value (user[email]=alice@example.com&user[password]=hunter2).
• A debug print of params after the failure confirmed params.user = {email: "alice@example.com", password: "hunter2"} — exactly the expected shape.
• After adding the debug print, wheels reload-ing, then removing the print and reloading again, subsequent POSTs to /signup returned a clean 302 to /posts and the user row was created correctly.
• The reporter could not reproduce after the second reload, even after wheels stop && wheels start.

Hypothesis (not verified)

Possible model-loader cache state on the very first reload after a brand-new model file is added — the User.cfc object initialization may see a stale property bag where this.email is whatever struct-shaped intermediate the property bag holds before the request-time bind happens. Once Lucee compiles + Wheels' model loader hands out the second-and-onward instance, the cache is correct and the issue self-heals.

If that's right, the underlying bug is in the model-loader's first-instance pathway after a ?reload=true that introduced a new model. It would hit any new model whose first instance is created inside an action, not just User.

What would help when reproducing

• Watch application.wheels.models.User inspectability across the boundary
• Capture the value of this.email via a dump(this.email) BEFORE the Trim(LCase(...)) call
• Check whether onMissingMethod or a property-bag initializer is involved

Reproducer (reportedly intermittent)

1. wheels new blog then walk chapters 1-5 of the tutorial
2. Add app/models/User.cfc per chapter 6 step "Add a User model"
3. Run the matching migration
4. wheels reload
5. POST to /signup immediately

If the bug fires, the fix is wheels reload once more (the second reload was sufficient on the original run).

Workaround for tutorial users

Reload twice before the first signup attempt, OR wheels stop && wheels start instead of reload after adding the User model. The chapter's checkpoint (Visit /signup, create an account...) doesn't currently mention either workaround.

Related context

• Originally observed on snapshot 4.0.0-SNAPSHOT+1667, brew-installed.
• Surfaced as F12 in the 2026-05-01 fresh-VM onboarding report.
• The chapter-6 CSRF inheritance fix in #2404 made CSRF semantics correct on a fresh signup form — but the cast error fires AFTER CSRF passes (it's deeper in the model lifecycle), so fix(controller): super.config() in chapter 6 + generator templates so CSRF inherits (F10) #2404 likely doesn't touch this.

[wheels-bot]

Wheels Bot — Triage

Classified as bug.

The report has a concrete failure mode (Can't cast Complex Object Type Struct to String on LCase(this.email)) with a verified observation that params.user.email is a plain string at the time of failure, plus a reproducer tied to "first POST after ?reload=true that introduced a new model." That is observable wrong behavior, not a feature/design ask.

Suspected layer

model — see .ai/wheels/ for canonical patterns (specifically the model section in CLAUDE.md § Model Quick Reference and cross-engine notes in .ai/wheels/cross-engine-compatibility.md).

The user-code line that throws (Trim(LCase(this.email))) is a symptom; the root cause hypothesis is that this.email is bound to a struct-shaped intermediate on the very first instance of a newly-introduced model after a cold reload — i.e. the model-loader / property-bag pathway, not the user's callback.

Fix sketch

Likely target files in vendor/wheels/model/: properties.cfc (how this.<property> is populated from params.user) and the first-instance initialization path that runs after ?reload=true registers a new model class. Cross-reference with the model registration / dispatch handoff (vendor/wheels/model/create.cfc, plus wherever application.wheels.models.<Name> is first stamped). The fix shape is probably: ensure the property assignment that exposes this.email is bound to the scalar form value before any callback runs, even on the first cold instance — or invalidate/rebuild the property bag on the reload that first registers a new model so the second-reload workaround isn't required.

Propose-fix will need to (a) reproduce the cold-reload-then-first-POST sequence, ideally via the onboarding harness (tools/test-onboarding.sh, phases 4-5), and (b) capture this.email and the model's property bag before the callback runs to confirm the hypothesis before patching.

Confidence: low

The bug is reported as intermittent and self-healing after a second reload; the model-loader cache hypothesis is explicitly unverified, more than one layer (dispatch reload + model registration + property assignment) is plausibly involved, and the fix shape is not obvious from the issue body alone.

<!-- wheels-bot:triage:2412 -->
<!-- wheels-bot:triage-class:bug -->