COLDBOX-1419 - Fix scheduled tasks loading module components on Adobe ColdFusion

[homestar9]

Summary

Fixes COLDBOX-1419.

On Adobe ColdFusion with IIS, scheduled tasks could fail when loading a handler, model, or scheduler from a module.

Scheduled tasks run in the background without a normal web request. Because of this, Adobe ColdFusion sometimes looks for module components in the wrong folder and shows an error like:

Could not find the ColdFusion component or interface
modules.mymodule.handlers.Maintenance.

The problem seemed random because the task worked if a web request had already loaded the component. It also did not happen in CommandBox, where component paths are handled differently.

This issue caused two module tasks to fail every night on an ACF 2023 and IIS site.

These failures also triggered COLDBOX-1420, which caused additional “Instance not found” errors until ColdBox was reinitialized. That is a separate bug and is not fixed in this PR.

What changed

This PR ensures the CF engine knows where every module is located.

• ModuleService now saves a mapping for each module folder it finds.
• It also saves mappings for modules registered with a custom path.
• ColdBoxScheduledTask.run() applies those mappings on the scheduled task’s background thread before running the task.

Scheduled task threads do not go through the normal web request setup, so they need to apply these mappings themselves.

If applying the mappings fails, ColdBox logs the error and still tries to run the task. This keeps the existing behavior where scheduled task errors are not rethrown.

Tests

Added tests to confirm that:

• Module search folders are added to the mapping registry.
• Modules registered with a custom path are added to the registry.
• Existing classMapping support still works.
• Scheduled tasks apply module mappings before running.
• A mapping error does not stop the scheduled task.

The full test suites pass with no failures on:

• BoxLang using CFML compatibility
• Lucee 5+
• Adobe ColdFusion 2023, 2025

Notes

• CommandBox-based CI cannot reproduce the original IIS problem, so the tests verify the behavior that fixes it.
• While reviewing this code, I noticed that ModuleService.unload() does not remove old entries from mappingRegistry. This was already happening and is not changed in this PR.
• Possible follow-up work includes updating the Scheduled Tasks documentation and adding module mappings to the application templates.

Jira Issues

• https://ortussolutions.atlassian.net/browse/COLDBOX-1419
• Related:https://ortussolutions.atlassian.net/browse/COLDBOX-1420

Type of change

• Bug Fix

Checklist

• My code follows the style guidelines of this project (cfformat run on touched files: no changes beyond the fix)
• I have commented my code, particularly in hard-to-understand areas
• I have added tests that prove my fix is effective (4 new specs in InjectorLiveTest.cfc: mapping kept after a failed lookup with a retry that re-throws the original error instead of InstanceNotFound; recovery once the missing file is restored; processMappings() keeps the failed mapping; multi-name mappings keep all names)
• New and existing unit tests pass locally with my changes (full wirebox suite: Adobe 2023 189/189, BoxLang 1.15 187 pass + 2 engine skips, Lucee 5.4 188 pass + 1 engine skip)

[Copilot]

Pull request overview

This PR addresses COLDBOX-1419 by ensuring Adobe ColdFusion scheduled tasks can reliably resolve module components when running on background threads (e.g., behind IIS) where CFML mappings may be missing or lost between requests. It does this by persisting module-related mappings in ModuleService and replaying them at task execution time in ColdBoxScheduledTask.run().

Changes:

• Persist module search-folder mappings and explicitly-registered module path mappings into ModuleService.mappingRegistry.
• Replay module mappings on the scheduled task background thread before executing the task body.
• Add regression tests covering mapping registry population, mapping replay behavior, and “mapping replay failure does not block task execution”.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/specs/web/services/ModuleServiceTest.cfc	Adds assertions that module search folders and explicitly registered module paths are stored in the mapping registry.
tests/specs/async/tasks/ColdBoxScheduledTaskSpec.cfc	Adds tests verifying mappings are replayed before task execution and that replay errors don’t prevent task success.
system/web/tasks/ColdBoxScheduledTask.cfc	Replays module mappings (via ModuleService.loadMappings()) prior to running the scheduled task.
system/web/services/ModuleService.cfc	Stores mappings for module scan locations and explicit module registration paths; leverages existing loadMappings() replay mechanism.
changelog.md	Documents the fix under Unreleased.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.