Lucee 5 to 6 Migration Guide

What actually changed in Lucee 6

Most CFML code runs unchanged. The changes that matter live around the edges, in configuration, defaults, and a handful of deliberate behaviour fixes:

• Configuration moved from XML to JSON. The old lucee-server.xml gives way to .CFConfig.json. Lucee converts your existing configuration automatically on first start, but treat the conversion as something to verify, not trust.
• Single-mode admin is the new default. The separate server and web admin contexts of Lucee 5 merge into one. If your setup leaned on per-web-context settings, review how they map before cutover (multi-mode still exists in 6, but is gone in 7).
• The Java baseline moved. Lucee 6.2 dropped Java 8; Java 11 is the minimum and Java 21 (LTS) is the recommended runtime. Plan the JVM upgrade as part of the migration, not after it.
• Several defaults changed: session cookies now default to SameSite=Lax and HttpOnly; Lucee trusts the JVM's certificate store instead of shipping its own (SSLCertificateInstall() no longer functions); cflocation stops appending session tokens by default; and in 6.2 the default application log level became ERROR, so logs go quieter.
• Some behaviours were aligned with Adobe ColdFusion: cfqueryparam no longer silently converts empty strings to null (empty values into numeric parameters now throw, as on ACF); string member functions iterate characters rather than list items; numberFormat() rounding matches ACF; queryMap() returns a new query instead of mutating in place; and === now compares type as well as value.
• The ORM extension changed hands. Hibernate ORM on modern Lucee is the Ortus ORM extension, the maintained fork of the old Lucee extension. If your app uses ORM, this swap is part of your migration.

Performance is the payoff: by the project's own measurements, Lucee 6.2 is up to 50% faster than 5.4 for some operations, helped by preciseMath defaulting off again in 6.2.

Pre-flight checklist

An hour of inventory saves a weekend of surprises. Before touching anything:

1. List your extensions. Every Lucee extension in the admin, plus anything installed manually. Check each has a 6.x-compatible release; ORM users note the Ortus extension above.
2. Record your Java version and plan the move to Java 21 LTS.
3. Export your configuration. The community-standard tool is CFConfig (via CommandBox), which exports datasources, mappings, scheduled tasks and settings to JSON you can diff and re-import.
4. Inventory scheduled tasks, datasources and mail servers independently of the export, so you can verify nothing was lost in translation.
5. Grep the codebase for the breaking-change hotspots: cfqueryparam calls that may receive empty strings for numeric types, SSLCertificateInstall, === comparisons, string member functions used on delimited lists, code relying on queryMap() mutating, and anything reading session cookies that HttpOnly will now hide from JavaScript.
6. Note your framework versions. ColdBox, CFWheels and FW/1 all run on Lucee 6; older releases of each may not, so check whether a framework upgrade rides along.

The upgrade, step by step

1. Stand up a test environment on Lucee 6.2 with your target Java version. CommandBox makes side-by-side engines trivial; alternatively a staging environment on your host (ours are free to spin up on request) does the same job with production-shaped infrastructure.
2. Import your configuration from the CFConfig export and verify datasources, mappings, scheduled tasks and mail settings arrived intact.
3. Pre-scan the codebase. Lucee's mapping compile feature will compile your entire application ahead of time and surface compile-time incompatibilities in one pass, rather than one error page at a time.
4. Run your regression tests, and manually exercise the areas the engine changed: anything date-heavy, anything relying on null handling, PDF generation, session behaviour across logins, and outbound HTTPS calls (the JVM certificate store change bites here, especially self-signed internal certificates).
5. Soak it. Leave staging running under realistic load for a few days; watch logs at the new default levels and confirm scheduled tasks fire.
6. Cut over with a rollback plan. Keep the Lucee 5 environment intact until the new one has survived a full business cycle. A migration you can reverse is a migration you can do calmly.