Lucee 5.4 is stable, familiar, and still doing useful work in production. That is exactly why the move to Lucee 6 should not be treated like a quick patch. A major-version upgrade can expose hidden assumptions in extensions, Java integrations, database drivers, error handling, logging, and older CFML patterns.
This checklist walks through what to verify before production changes. The goal is simple: build confidence in staging, catch the ugly surprises early, and make the production cutover feel boring.
Prerequisites before you start
Before you install anything, collect the pieces that define your current Lucee 5.4 environment.
At minimum, have:
A recent application backup
A database backup or restore point
A copy of the current Lucee server and web context settings
A list of installed Lucee extensions
JDBC driver versions
Java version details
Web server connector details
Application framework and CMS versions
Scheduled task definitions
Known production error examples
A staging environment that matches production closely
Do not rely on memory. Lucee upgrades often go wrong because a “small” runtime dependency was installed years ago and nobody wrote it down.
If possible, take screenshots or exports of the Lucee Administrator settings before changing anything. Pay special attention to datasources, mappings, mail servers, caches, ORM settings, request limits, security settings, and scheduled tasks.
1. Inventory your current Lucee 5.4 application stack
Start by documenting what is actually running. A clean inventory gives you something to compare against after the Lucee 6 install.
Include the full stack, not just CFML code:
Area | What to capture |
Lucee runtime | Exact Lucee 5.4 version, server context settings, web context settings |
Java | Installed Java version, JVM arguments, memory settings |
Extensions | Extension names, versions, and whether they are required at startup |
Database | Datasource settings, JDBC driver versions, connection options |
Web server | Apache, Nginx, IIS, Tomcat, or connector configuration |
Application code | Frameworks, CMS packages, custom libraries, vendor modules |
Jobs | Scheduled tasks, background workers, queue consumers |
Integrations | Java libraries, REST APIs, SOAP clients, file storage, mail services |
The most useful inventory is one you can test against. After you install Lucee 6 in staging, walk down the list and confirm each item still loads, connects, and behaves as expected.
This is also the right time to clean up old assumptions. If a datasource points to a retired database, remove it from the test plan. If an extension is installed but unused, decide whether it belongs in the new runtime at all.
2. Check extensions, JDBC drivers, and Java integrations
This is the part most likely to cause upgrade surprises.
Lucee 6 updated its underlying Java baseline and several bundled libraries. That does not mean every custom extension, JDBC driver, or Java dependency will break. It does mean each one needs explicit compatibility testing.
Do not assume that something working on 5.4 will load cleanly on 6.
Check these items one by one:
Lucee extensions installed through the Administrator
Manually deployed extensions
JDBC drivers placed in custom library paths
Java classes called from CFML
Third-party JAR files
PDF, image, spreadsheet, mail, or compression libraries
Search, cache, ORM, or cloud storage integrations
A simple way to test is to boot Lucee 6 in staging with the same extensions and libraries, then watch startup logs closely. Some failures appear immediately. Others only show up when a specific code path runs.
For database drivers, test more than a successful connection. Run basic read and write queries, transaction blocks, stored procedure calls if you use them, and any query features your application relies on.
For Java integrations, test the exact CFML calls that load and use Java classes. Pay close attention to classpath behavior, constructor calls, method signatures, and library conflicts.
3. Compare your code against Lucee migration notes
After dependency checks, audit your CFML code for removed, changed, or deprecated behavior.
Major Lucee versions tend to formalize changes that may have been warned about before. Some older tags or functions may still work. Others may behave differently. A code search before the upgrade is much cheaper than a production debugging session after it.
Use Lucee’s official migration notes as the source of truth. Build a small search list from the notes, then grep the codebase.
For example, check:
Deprecated tags
Deprecated functions
Changed default settings
Changes in strictness or type handling
Admin settings with new defaults
Security-related behavior changes
Serialization behavior
Date, time, and locale behavior
Query handling edge cases
A direct command may look something like this in a Unix-like environment:
```bash
grep -R "tagOrFunctionName" ./app
```
For a larger application, put the terms in a script and produce a report. Do not try to fix everything by hand while searching. First, build the list. Then sort findings into three groups:
Finding type | What to do |
Must fix before upgrade | Code is likely to fail or produce wrong output |
Should test in staging | Code may behave differently under Lucee 6 |
Can schedule later | Code is old but not blocking the upgrade |
This keeps the audit useful. The point is not to modernize the whole application in one pass. The point is to remove upgrade blockers and identify risk.
This step matters even more if the application has been maintained for many years. Old CFML code often contains patterns that work because the runtime has been forgiving. A major upgrade can make those hidden assumptions visible.
4. Rebuild your staging environment as closely as possible
A staging environment only helps if it resembles production. A clean Lucee 6 install with a tiny test page proves the server runs. It does not prove your application is ready.
Match the production environment where it matters:
Same operating system family
Same Java major version planned for production
Same web server connector pattern
Same Lucee Administrator settings
Same datasources and driver versions
Same application mappings
Same file permissions model
Same scheduled task behavior
Same cache provider, if used
Same environment variables and secrets pattern
You do not need to copy production data in full. In many cases, you should not. Use scrubbed or representative data that covers real application states: active users, old records, large files, missing optional fields, archived content, and edge-case dates.
Run the application like a user would. Log in, submit forms, generate reports, upload files, send email through a test mailbox, run background tasks, and hit admin-only features. If your app has an API, run existing API tests or create requests for the endpoints that carry business-critical traffic.
The more realistic the staging traffic, the more useful the result.
5. Test error handling and logging on purpose
Do not wait for production to throw the first real error.
Exception handling is one of the areas where small runtime differences can hurt the most. The application may seem fine until a datasource times out, a template is missing, an API returns bad data, or a user submits unexpected input.
Create a short list of known failure cases and trigger them in staging.
Test cases might include:
Missing template
Bad route or unknown URL
Invalid form submission
Database connection failure
Query error
Failed remote API call
File permission issue
Mail server failure
Unhandled exception inside application code
Custom error page rendering
For each test, confirm four things.
The user should see the expected error page. The logs should include enough detail to diagnose the issue. Sensitive details should not leak to the browser. Alerts or monitoring should still fire if they did before.
Check both Lucee logs and application logs. If you use a logging library or external collector, make sure messages still show the right severity, timestamp, request context, and stack trace details.
This is a key part of any Lucee 5.4 to Lucee 6 upgrade because error paths are often under-tested. Production rarely fails in the ways your happy-path test script covers.
6. Verify application settings and runtime behavior
After Lucee 6 is running in staging, compare behavior that depends on runtime configuration.
Start with Lucee Administrator settings. Some settings may not carry over the way you expect if you rebuild rather than upgrade in place. Others may exist but have different defaults.
Check these areas carefully:
Datasources and connection pooling
Mail server settings
Mappings and component paths
Cache connections and object cache use
Session and client management
Request timeout settings
File upload limits
Regional and locale settings
Time zone settings
Security and access settings
ORM configuration
Scheduled task definitions
Then move from settings to actual behavior.
Confirm sessions persist as expected. Confirm caches can be cleared and repopulated. Confirm file uploads land in the right place with the right permissions. Confirm generated PDFs, images, spreadsheets, or exports still work if your application creates them.
If the app depends on exact date formatting, number formatting, or time zone behavior, test those paths with real examples. Runtime upgrades can expose code that relied on defaults instead of explicit settings.
7. Run performance and load checks before the cutover
A successful page load is not the same as a ready production system.
Run enough load in staging to catch obvious problems. You do not need a perfect production simulation, but you should know whether the Lucee 6 environment handles normal traffic patterns without strange pauses, connection exhaustion, or memory pressure.
Watch:
JVM memory use
Garbage collection behavior
Request times
Thread activity
Database connection pool use
Slow queries
Cache hit and miss patterns
Log volume
CPU during scheduled tasks
Compare against your Lucee 5.4 baseline where possible. If you do not have formal metrics, use what you can gather now. Even a simple before-and-after comparison on common pages is better than guessing.
Pay attention to scheduled tasks and background jobs. These can cause problems after cutover because they often run outside manual test paths. Trigger them in staging and confirm they finish cleanly.
8. Plan the production cutover and rollback path
The safest production upgrade is the one you can reverse without panic.
Before the cutover, define:
The maintenance window
Who will perform each step
What gets backed up
What services must stop and start
How to verify the new runtime
What counts as a failed cutover
How rollback works
Who makes the rollback decision
Write the steps down. A checklist reduces mistakes when the clock is running.
A practical cutover plan might look like this:
Announce the maintenance window.
Stop scheduled tasks or background workers.
Put the application into maintenance mode if needed.
Take final backups.
Deploy or switch to the Lucee 6 runtime.
Confirm Lucee starts cleanly.
Run smoke tests.
Re-enable scheduled tasks.
Watch logs and metrics.
10. Keep the rollback window open until the system has handled real traffic.
Do not make unrelated changes during the same window. Avoid combining the Lucee upgrade with a framework upgrade, database migration, major code release, or server move unless there is no other option. Smaller changes are easier to debug.
9. Treat Lucee 6 as a bridge if Lucee 7 or 8 is the goal
If the long-term plan is Lucee 7 or Lucee 8, resist the urge to jump multiple major versions in one move.
A staged path is usually lower risk:
```text
Lucee 5.4 → Lucee 6 → Lucee 7 or 8
```
Each hop gives you a smaller compatibility problem to solve. That matters if your application depends on a CMS, framework, plugin system, or vendor package that only supports certain Lucee versions.
The staged approach also gives you better evidence. After the Lucee 6 upgrade, you can run production for a period, confirm stability, then plan the next move with fewer unknowns.
Think of Lucee 6 as a checkpoint. Once the app is stable there, the next upgrade discussion becomes clearer.
10. Confirm success after production is live
When production comes back online, do not stop at “the homepage loads.”
Run a short post-upgrade validation script:
Load public pages
Log in as a test user
Submit a safe test form
Confirm database reads and writes
Run a report or export
Check file uploads
Confirm email delivery through a test message
Trigger or inspect scheduled tasks
Review Lucee logs
Review application logs
Watch memory, CPU, request time, and database connections
Keep monitoring closely after real users return. Many upgrade issues appear only under normal traffic. Leave extra time after the cutover to inspect logs and respond quickly.
A good upgrade ends quietly. Extensions load. Drivers connect. Error pages behave. Logs are useful. Scheduled tasks run. Users do their normal work without noticing the runtime changed.
That is the real goal of the checklist: not a dramatic launch, just a controlled move from a known Lucee 5.4 system to a tested Lucee 6 environment with fewer surprises.