Part 5 of "From 2.x to 4.x: the field guide". CFWheels 2.x ran validation condition= and unless= strings through Evaluate(); Wheels 4.1 parses a small grammar and throws Wheels.InvalidValidationCondition for what it can't parse. This post lists the grammar 4.1.2 accepts, runs ten 2.x-style strings on 4.1.2 (three throw, seven give the wrong answer without an error), rewrites each one, covers the this.method() escape hatch and the two production conditions from the 4.1.1 CHANGELOG, and explains what Wheels 4.2 changes.
Part 4 of "From 2.x to 4.x: the field guide" covers public/Application.cfc, the app-owned file that a vendor/wheels/ swap never updates. It replays every template change from 4.0.0 to 4.1.2 one commit at a time: the DI container, the onError fallbacks, the fail-closed reload gate, the X-Wheels-Reload-Password header, IP-based debug access, the session cookie, the Adobe teardown handlers, the jBCrypt load path and the .env parser. A table says what each edit fixes, which release added it and whether skipping it fails safe, and the post shows what changed on Lucee 7 and Adobe ColdFusion 2025 after each edit.
Part 3 of "From 2.x to 4.1: the field guide" takes the example app from Wheels 3.0.0+33 to 4.1.2. It reads the real `wheels upgrade check` output before and after, explains why to run the check before swapping vendor/wheels, and walks the 14 commits: the framework swap, the 4.1 public/Application.cfc, plugin replacements, paginationNav(), the CSRF settings, a RocketUnit-to-WheelsTest conversion and validation conditions. It also covers the breakers only a real boot found: default='' in migrations, structs assigned to scalar columns, dates interpolated into where strings on 4.1.2, and a reload password the CLI and the app disagreed on.
Part 2 of "From 2.x to 4.1: the field guide" walks the nine commits that take the example app from CFWheels 2.2 to Wheels 3.0.0+33: moving code into app/ and assets into public/, the new public/Application.cfc, vendor/wheels pinned to 3.0.0+33, path and test fixes, and the problems the 3.0 guide doesn't mention: events/ has to move, plugins/ stays at the root, a caret range can install a 4.0 development build, joinType="left" silently drops a nested join, and a 2.3 validatesConfirmationOf change breaks login.
The first post in "From 2.x to 4.1: the field guide". Going from Wheels 2.x to 4.1 takes two passes: 2.x to 3.0.0+33 (the layout move), then 3.0 to 4.1 (the framework swap and the 4.x breaking changes). This post shows what each pass touches, which files no upgrade command ever touches, and the real CFWheels 2.2 app we upgrade on camera, wheels-dev/cfwheels-example-app, with one branch and one commit per step.
Wheels 4.0 lands with seven breaking changes and a Legacy Compatibility Adapter for teams that cannot touch every call site this quarter. This post is the honest map: what breaks, how to detect it, how to fix it, and when the adapter is the right answer instead.
