Common Errors

Error / symptom	Cause	Resolution
`undefined: templ` or compile errors after pulling	Runtime dependency missing, or generated files are stale	`go get github.com/a-h/templ@latest`, then `templ generate`
Page shows old markup after editing a `.templ` file	Generated `*_templ.go` is stale	Run `templ generate`; keep `templ generate --watch` running in dev
LSP not activating in the editor	`templ lsp` missing, filetype not registered, or no tree-sitter grammar	Install the CLI (`go install github.com/a-h/templ/cmd/templ@latest`), register the templ filetype, add tree-sitter-templ for highlighting
Text appears escaped (`<` etc.), or untrusted HTML renders raw	Expressions are always HTML-escaped; raw output needs explicit opt-in	Use script templates or `templ.JSONScript` for data; `templ.Raw` only for trusted markup
Fragment request returns the whole page	Handler lacks `templ.WithFragments`, or the request lacks the fragment id	Serve with `templ.Handler(page(), templ.WithFragments("id"))` and make sure the request carries the id
Status/header changes fail after streaming starts	First bytes already flushed	Set status and headers before the first flush; only use `templ.WithStreaming()` + `templ.Flush()` when late changes are not needed

Diagnosing stale output

Suspect the generated file first. A checkout that skipped templ generate compiles fine and serves old HTML. Generated files are build artifacts - whether you commit them or generate in CI, what ships is what was generated last.

Run templ generate --watch in a terminal
Save a .templ file and confirm the generated file changes
If it does not, check you are editing a file the generator sees (same module, correct path)

See Generated Code for why this happens. The version stamp baked into each generated file exists precisely to make stale files detectable.

Diagnosing LSP problems

The language server needs three cooperating pieces; check them in order:

The templ CLI is installed and on PATH (templ lsp starts without an error)
Your editor has the templ extension or the filetype registered for .templ
tree-sitter-templ is present for syntax highlighting

If highlighting works but completions do not, restart the LSP after installing the CLI - editors cache a failed first attach.

Diagnosing escaping surprises

Escaping is not a bug; it is the default. Map your case:

Data for client JS: templ.JSONScript
Values inside <script> strings: script templates with {{ name }} placeholders
Trusted, pre-built HTML: templ.Raw, and nothing else

Warning: templ.Raw disables escaping for its argument. Anything user-influenced that reaches it is an injection vector.

Diagnosing fragment mismatches

When a fragment request returns the full page, check both sides in order:

The handler call includes templ.WithFragments("id")
The subtree is wrapped in templ.Fragment("id") { ... }
The outgoing htmx request actually carries the fragment id