Repository navigation
Guides page fails on Adobe ColdFusion with ‘Unable to add text to HTML HEAD tag’ error #2569
Description
Describe the bug
When running a Wheels application on Adobe ColdFusion and navigating to the Guides page, the following error is thrown:
Unable to add text to HTML HEAD tag.
ColdFusion was unable to add the text you specified to the output stream.This is probably because you have already used a CFFLUSH tag in your template or buffered output is turned off.
As a result, the Guides page does not render.
To Reproduce
Steps to reproduce the behavior:
- Run a Wheels application using Adobe ColdFusion.
- Navigate to the Guides page.
- Observe the error shown above.
Expected behavior
The Guides page should render successfully on Adobe ColdFusion without throwing errors related to adding content to the HTML <head>.
Screenshots
Desktop:
- OS: Any
- CFML Engine: Adobe ColdFusion
Additional context
This error usually occurs in Adobe ColdFusion when code attempts to add content to the after output has already started. Possible causes include:
- Output being generated before
contentFor("head")or similar helpers are called - Use of
cfflush - Response buffering differences between Lucee and Adobe ColdFusion
Activity
wheels-bot commentedon May 12, 2026
Wheels Bot — Triage
Classified as bug.
Suspected layer
view— see.ai/wheels/views/for canonical patterns. The affected files are the framework's built-in public views:vendor/wheels/public/views/guides.cfmandvendor/wheels/public/docs/guides.cfm.Fix sketch
vendor/wheels/public/docs/guides.cfm:47injects a meta refresh tag via<cfhtmlhead text="...">. The wrapper view (vendor/wheels/public/views/guides.cfm) includes../layout/_header.cfmbefore including../docs/guides.cfm, so by the timecfhtmlheadruns the response has already streamed past</head>. Lucee tolerates this; Adobe CF throws "Unable to add text to HTML HEAD tag." The fix is to stop relying oncfhtmlheadafter the layout has rendered — emit the redirect another way (e.g.<cflocation url="..." addtoken="false">early, a plain inline<meta http-equiv="refresh">inside the rendered body, or hoist thecfhtmlheadcall above the_header.cfminclude).Confidence:
mediumCross-engine concern (Lucee tolerates late
cfhtmlhead, Adobe doesn't) fires the auto-downgrade rule — fix needs verification against both engines, and the right replacement strategy is a small design choice rather than a one-line swap.<!-- wheels-bot:triage:2569 -->
<!-- wheels-bot:triage-class:bug -->
fix(view): emit /wheels/guides redirect from body so Adobe CF stops e…