Breaking Changes between Lucee 6.2 and 7.0
Breaking Changes between Lucee 6.2 and 7.0
This document outlines the breaking changes introduced when upgrading from Lucee 6.2 to Lucee 7.0.
Be aware of these changes when migrating your applications to ensure smooth compatibility.
Other Breaking Changes in Lucee Releases
- Breaking Changes between Lucee 5.4 and 6.0
- Breaking Changes Between Lucee 6.0 and 6.1
- Breaking Changes between Lucee 6.1 and 6.2
Java Support
- Java 24 for best performance!
- Java 21
- Java 11 is supported, but it's slower and support will be removed in the near future. Tomcat 11 requires Java 17
- Java 8 is no longer supported
Switching to Jakarta (from Javax)
Lucee 6.2 introduced support for jakarta (Tomcat 10+) etc, but was still javax based
Lucee 7.0 is now based on Jakarta. As such, Tomcat 9.0 (or older) is no longer supported, we recommend doing a fresh install.
Lucee/script-runner was updated to include jakarta.jakartaee-api
Javax to Jakarta Namespace Ecosystem Progress
Common Migration Issues and Solutions
When upgrading to Lucee 7.0, you may encounter errors related to missing javax or jakarta classes. Lucee 7 provides clear, actionable error messages to help you resolve these issues quickly.
Scenario 1: Running Lucee 7 on Jakarta Containers (Tomcat 10+) with Old Extensions
Symptom: You see errors like:
java.lang.ClassNotFoundException: javax.servlet.jsp.tagext.TryCatchFinally not found by redis.extension
Cause: Extensions (Redis, Lucene, etc.) that were compiled against javax.servlet APIs are not compatible with Jakarta-based containers.
Solution: Update your extensions to Jakarta-compatible versions. Check the Lucee extension marketplace or your extension provider for updated versions that support Jakarta EE.
Scenario 2: Running Lucee 7 on Javax Containers (Tomcat 9 or earlier)
Symptom: You see errors about missing jakarta classes:
java.lang.NoClassDefFoundError: jakarta/servlet/http/HttpServletRequest
Cause: Lucee 7 requires Jakarta EE servlet APIs, which are not present in javax-based containers like Tomcat 9.
Recommended Solution: Upgrade to a Jakarta-based servlet container:
- Tomcat 10.1+ (recommended)
- Jetty 11+
- Other Jakarta EE 9+ compatible containers
Temporary Workaround: If you cannot immediately upgrade your servlet container, you can add Jakarta servlet APIs to your classpath:
- Maven dependency: jakarta.servlet-api on Maven Central
- Download the JAR and add it to your servlet container's
libdirectory
Note: Adding Jakarta APIs is only a temporary solution. Upgrading to a Jakarta-based container is the proper long-term approach.
Loader Change
Lucee 7.0 we have changed the Loader API, so that in place upgrades via the admin aren't supported OOTB.
The Loader Jar is found in the lucee/lib directory, i.e. lucee-6.2.0.321.jar.
To upgrade to Lucee 7.0 (if you are already running Tomcat 10.1), you will need to
- Stop Lucee
- Replace that jar with a 7.0 version (
lucee.jar) from https://download.lucee.org/ - Restart Lucee.
The latest 5.4 and 6.2 releases will automatically ignore any attempts to do an in place upgrade, if the Loader jar is unsupported.
If you try upgrading an older release without these loader version checks, you will get a 500 error on startup.
To get your Lucee instance back up and running if you experience this problem, stop Lucee and delete any lucee 7 .lco files from lucee/tomcat/lucee-server/patches and restart.
Single Mode Only
Lucee 7.0 only supports Single Mode, which was introduced with Lucee 6.0.
Properly Scope Internal Tag Variables in Lucee Functions
Prior to Lucee 7, tag results like CFQUERY, CFLOCK, CFFILE, CFTHREAD were written into the default variables scope.
With Lucee 7, when these tags are used within a function, these are now written to the local scope.
This should have minimal impact on existing code and may avoid some concurrency race conditions, hence the change.
Restore old behavior (if needed):
LUCEE_TAG_POPULATE_LOCALSCOPE
SysProp: -Dlucee.tag.populate.localscope
EnvVar: LUCEE_TAG_POPULATE_LOCALSCOPE
Controls whether tags like cflock and cfquery populate their default result variables to local scope when inside a function. When `true`, variables go to local scope. When `false`, restores pre LDEV-5416 behavior where variables go to variables scope
Type: boolean | Default: true | Introduced: 7.0.1.13
Enabled correct encoding of spaces in urls with CFHTTP
Older versions of Lucee double encoded spaces in CFHTTP, causing problems calling some APIs
Remove support for loginStorage="cookie" and sessionStorage="cookie"
These are insecure and seldom used
Enable quoted-printable for CFMAIL by default
For better HTML email support, Lucee 7 defaults to 7-bit encoding
LUCEE_MAIL_USE_7BIT_TRANSFER_ENCODING_FOR_HTML_PARTS
SysProp: -Dlucee.mail.use.7bit.transfer.encoding.for.html.parts
EnvVar: LUCEE_MAIL_USE_7BIT_TRANSFER_ENCODING_FOR_HTML_PARTS
Enabled by default in Lucee 7
Type: boolean | Default: true
EHCache is no longer bundled
Still available as an extension, it is just no longer bundled in the default distribution.
This reduced the size of the full lucee.jar from 84 Mb to 64 Mb.
LDEV-5485
Enable LUCEE_COMPILER_BLOCK_BYTECODE by default
Prevents cfml files containing java bytecode from being executed
LUCEE_COMPILER_BLOCK_BYTECODE
SysProp: -Dlucee.compiler.block.bytecode
EnvVar: LUCEE_COMPILER_BLOCK_BYTECODE
Controls whether Lucee blocks the direct execution of precompiled bytecode files (.cfm). When `true`, only source code CFML files are allowed. Bytecode execution is blocked by default in Lucee 7 for security reasons
Type: boolean | Default: true | Introduced: 6.1.1.114
LDEV-5485 Lucee CVE-2024-55354
CFCACHE now defaults to ignoring query_string
Prior to Lucee 7, Lucee would include the query string in the cache key. Changed to match ACF behaviour since CF9.
The attribute, useQueryString=boolean was added as part of this change
CFIMAP stopOnError added
Default is true, previously was effectively false
Pending changes (not yet implemented)
All proposed changes are listed in the sprint board for 7.0
Please raise any discussions regarding these changes on the dev forum, not in the individual tickets