Debug an HTMX exchange

When an HTMX interaction misbehaves, debug one exchange from left to right. Resist the urge to change several attributes at once. You will not know which change fixed it, and you may hide the real bug.

1. Confirm HTMX loaded. The script request should succeed and htmx.version should exist.
2. Trigger the interaction with the Network panel open. If no request appears, inspect the natural event and hx-trigger.
3. Check the method, final URL, query string or body, and HX-* request headers.
4. Check the response status, Content-Type, HTMX response headers, and raw HTML body.
5. Inspect the resolved target and swap strategy.
6. Check the console for htmx:targetError, htmx:swapError, or browser parsing errors.

Classify the failure before fixing it:

• no request: loading or trigger problem
• wrong request: method, URL, or parameter problem
• wrong response: server route, validation, or template problem
• correct response but wrong DOM: target, swap, or invalid HTML context
• correct DOM but poor experience: focus, indicator, history, or accessibility problem

Reproduce the request outside HTMX with curl when necessary. If the endpoint itself returns the wrong fragment, no client attribute can repair it. I spend most of my HTMX debugging time on steps 3 and 4, not on swap attributes.

One quick habit: after a swap, open the Elements panel and find the target node. Compare its inner HTML to the response body byte for byte. If they differ, the browser may have repaired invalid markup, or you targeted the wrong node.

Try this on your own project: break one interaction on purpose, then walk the six steps above until you can name the failure class in one sentence.