From 454518efb38371b3dff564a20fb3b52ea18dc4b3 Mon Sep 17 00:00:00 2001 From: Gian Tschingt Date: Sat, 31 Oct 2026 12:21:40 +0100 Subject: [PATCH 1/2] LDEV-5272 document LUCEE_EXTENSIONS_FAIL_ON_ERROR --- docs/recipes/environment-variables-system-properties.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/recipes/environment-variables-system-properties.md b/docs/recipes/environment-variables-system-properties.md index bce611325..25b1eb350 100644 --- a/docs/recipes/environment-variables-system-properties.md +++ b/docs/recipes/environment-variables-system-properties.md @@ -87,6 +87,15 @@ Defines a comma-separated list of Lucee extensions to install when starting up. The current list of installed extensions is available via the Lucee admin. +#### LUCEE_EXTENSIONS_FAIL_ON_ERROR + +*SysProp:* `-Dlucee.extensions.fail.on.error` +*EnvVar:* `LUCEE_EXTENSIONS_FAIL_ON_ERROR` + +A boolean value (default `false`) that makes an invalid `LUCEE_EXTENSIONS` fatal on startup. When `true`, the startup is aborted if an extension defined in `LUCEE_EXTENSIONS` cannot be installed or an entry of the list cannot be parsed. When `false`, the error is written to the deploy log and to stderr and the startup continues. + +In warmup mode (`LUCEE_ENABLE_WARMUP`) such a failure always makes the process exit with a non-zero exit code, independent of this setting. + #### LUCEE_EXTENSIONS_CONFIG_ONLY *SysProp:* `-Dlucee.extensions.config.only` From a55b36a97f8a782652f409cafdc0f4471a8be045 Mon Sep 17 00:00:00 2001 From: Gian Tschingt Date: Sat, 31 Oct 2026 12:29:09 +0100 Subject: [PATCH 2/2] LDEV-5272 document the warmup failure for invalid LUCEE_EXTENSIONS --- docs/recipes/warmup.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/recipes/warmup.md b/docs/recipes/warmup.md index 0e9ef9e06..a8e2e1c73 100644 --- a/docs/recipes/warmup.md +++ b/docs/recipes/warmup.md @@ -93,6 +93,12 @@ If any configuration is invalid, the `RUN` step fails and the Docker build abort Warmup also installs the extensions defined in `.CFConfig.json` and stores them in the image, so the container doesn't download them at startup. See [[downloading-extensions]]. +### Invalid `LUCEE_EXTENSIONS` *(Lucee 9)* + +If an extension defined in `LUCEE_EXTENSIONS` (`lucee.extensions`) cannot be installed, or an entry of that list cannot be parsed, warmup fails: the error is written to stderr and the deploy log, `onBuild` is not called and Lucee exits with a non-zero exit code, so the Docker build aborts instead of producing an image with missing extensions. + +Outside of warmup, the same failure is only logged by default. Set `LUCEE_EXTENSIONS_FAIL_ON_ERROR=true` (`lucee.extensions.fail.on.error`) to abort a normal startup as well. See [[environment-variables-system-properties]]. + ## Upgrading to Lucee 7 Because Lucee 7 now validates all configuration sections during warmup, upgrading may cause your warmup to fail on settings that previously passed silently in Lucee 6.2. This is intended — it surfaces misconfigurations that were always there but hidden by lazy loading. Fix the reported settings and rebuild.