Upgrading from Wheels 3.x — the honest map

[bpamiri]

I just published a new post on blog.wheels.dev walking the 3.x → 4.0 upgrade as it surfaced for a real production codebase: https://blog.wheels.dev/upgrading-from-wheels-3x

What it covers

• Seven breakers the canonical guide flags as most likely to bite a real 3.x codebase: wheels snippets → wheels generate snippets, redirectTo() scope tightening on Lucee 7, testbox → wheelstest namespace, tests directory rename (functions/ → functional/), RocketUnit removed from core, CORS default flip (wildcard → deny-all), allowEnvironmentSwitchViaUrl off in prod + reload password required.
• The Legacy Compatibility Adapter — what it covers and what it does not. Notably: it does not shim application.wirebox or the wirebox.system.ioc.Injector class path, so apps that bootstrap WireBox in Application.cfc (the canonical 2.x pattern) must rewrite that file before first boot, adapter or no adapter.
• Things that bite at boot (from the field) — operational gotchas the canonical list does not cover:
  • Default rewrite.config 404s static assets in non-standard directories (/miscellaneous/, /javascripts/, /stylesheets/, /files/)
  • reloadPassword=... in .env does not satisfy the framework's empty-check; must wire via set(reloadPassword=env("WHEELS_RELOAD_PASSWORD")) in config/settings.cfm
  • Classpath jars need symlinking into Lucee Express lib/ext/ if you came from CommandBox libDirs
  • Lucee 6.x → 7 cross-version DB sessions throw InvalidClassException before onrequeststart.cfm runs — the AppSerial kill-switch cannot fire; one-time fix is to truncate the session-storage table after cutover

v4.0.1 heads-up

Most of the "things that bite at boot" are already being addressed in the forthcoming v4.0.1 — improved CLI defaults for rewrite.config, expanded wheels upgrade check coverage, and clarified canonical-guide docs on reloadPassword and the adapter's WireBox limits. A follow-up post will land when v4.0.1 ships, pointing back to this one for the lived-experience context.

Where to read more

• Full post: https://blog.wheels.dev/upgrading-from-wheels-3x
• Canonical upgrade guide: https://guides.wheels.dev/v4-0-0/upgrading/3x-to-4x/

If you are mid-upgrade and the post does not cover something you hit, please share — the audit trail is most useful when it is complete.