htmx-debugging

Imported from yardenshoham/onepiece (.agents/skills/htmx-debugging/SKILL.md). Install upstream with npx skills add yardenshoham/onepiece --skill htmx-debugging. Copyright stays with the author.

htmx 4 Debugging Guide

Quick Diagnostic Checklist

Work through these in order -- most issues fall in the first few:

1. Is htmx loaded? Check for htmx global in console, verify script tag
2. Is the element processed? Check element._htmx property exists
3. What htmx version? Check htmx.version -- the htmx 4 API is very different from htmx 2
4. Is the trigger correct? Defaults: click for most, change for inputs/selects/textareas, submit for forms
5. Is the target correct? Verify the CSS selector matches an existing element
6. Does the server return HTML? Not JSON -- check Content-Type and response body
7. Check the response status -- htmx 4 swaps ALL responses except 204 and 304 by default
8. Is inheritance set up? htmx 4 requires :inherited modifier on parent attributes
9. For extensions: Is the script loaded after htmx.js? If you set the extensions whitelist, the registration name must be in it. An unset whitelist allows every extension

Enable Debug Logging

Errors and warnings flow to console.error / console.warn by default. To also surface every event htmx dispatches:

<meta name="htmx-config" content='{"logAll": true}'>

or in the console:

htmx.config.logAll = true;

Observability tools (Sentry, DataDog RUM, LogRocket, etc.) capture console.* automatically, so htmx logs flow into your existing pipeline without any extra setup.

Event Monitoring Snippet

Paste this in the console to monitor the request/swap lifecycle:

['htmx:config:request', 'htmx:before:request', 'htmx:after:request',
 'htmx:before:swap', 'htmx:after:swap', 'htmx:finally:swap', 'htmx:error', 'htmx:finally:request']
.forEach(evt => document.body.addEventListener(evt, e => {
    console.log(evt, e.detail?.ctx?.request?.action, e.detail?.ctx?.response?.status, e.detail);
}));

To monitor what events a specific element is firing:

monitorEvents(htmx.find("#theElement"));

Common Issues and Solutions

Request Not Firing

Check the trigger:

• Is the event actually happening? Use monitorEvents() on the element
• Default triggers differ by element type -- an <input> won't fire on click
• If using hx-trigger="load", was the element in the DOM before htmx initialized?

Check synchronization:

• hx-sync may be dropping or queuing the request
• Check for hx-sync="closest form" or similar that might block it

Check confirmation:

• hx-confirm blocks until confirmed -- including js: async confirmation
• An htmx:confirm event listener calling preventDefault() without calling issueRequest() will block forever

Check for hx-ignore:

• A parent element with hx-ignore disables htmx for all children

Dynamic content:

• Elements added to the DOM after page load need htmx.process(element) to initialize htmx behavior
• Or use htmx.onLoad() to set up a callback for new content

Swap Not Happening

Check response status:

• 204 and 304 do NOT swap by default (controlled by htmx.config.noSwap)
• In htmx 4, 4xx and 5xx responses DO swap by default (unlike htmx 2!)
• If you need htmx 2 behavior: htmx.config.noSwap = [204, 304, '4xx', '5xx']

Check the target:

• Does the hx-target CSS selector match an existing element?
• Use browser devtools to run document.querySelector("your-selector") to verify

Check hx-swap:

• hx-swap="none" explicitly prevents swapping
• hx-swap="delete" deletes the target regardless of response

Check hx-select:

• If set, only matching elements from the response are used
• If nothing matches, nothing gets swapped

Check event listeners:

• An htmx:before:swap listener calling preventDefault() will cancel the swap

Wrong Content Being Swapped

Check selectors:

• hx-select might be matching the wrong element in the response
• hx-target might point to the wrong element

Check for OOB/partial interference:

• hx-swap-oob in the response swaps content by ID independently
• <hx-partial> tags in the response swap into their own targets
• In htmx 4, OOB swaps happen AFTER the main content swap (changed from htmx 2)

Check response headers:

• HX-Retarget, HX-Reswap, HX-Reselect override client-side attributes, and htmx applies them before hx-status
• hx-status:XXX attributes can change target, swap, select or history handling for one status code. htmx tries the exact code first, then NNx, then Nxx, and stops at the first match

Extension Not Working

1. Is the extension script loaded AFTER htmx.js?
2. If you set the extensions whitelist, is the extension name in it? An unset whitelist allows every extension
3. Does the name match exactly? It is case-sensitive, and the registration name is not always the file name. hx-sse.js registers as sse, hx-preload.js as preload, htmx-2-compat.js as compat
4. Check console for registration errors
5. htmx 4 extensions use htmx.registerExtension() not htmx.defineExtension() -- make sure you have an htmx 4 compatible extension

Inheritance Not Working

The #1 gotcha in htmx 4:

<!-- WRONG: children won't inherit this -->
<div hx-target="#output">
  <button hx-get="/a">A</button>
</div>

<!-- RIGHT: use :inherited modifier -->
<div hx-target:inherited="#output">
  <button hx-get="/a">A</button>
</div>

• htmx 4 requires :inherited modifier by default
• Set htmx.config.implicitInheritance = true to get htmx 2 behavior
• Check that it's on the PARENT, not the child

History/URL Issues

• hx-push-url and hx-replace-url require the URL to return a full page when accessed directly
• History restoration in htmx 4 does a full page request (no localStorage/sessionStorage cache)
• Set htmx.config.history = "reload" to do hard browser reloads on back/forward
• hx-status attributes with push:false can prevent URL updates on errors

CSS Transitions Not Working

• CSS transitions rely on element ID stability across swaps -- keep id attributes consistent
• htmx-swapping class is applied before swap, htmx-settling after
• For View Transitions API: enable with htmx.config.transitions = true or hx-swap="... transition:true"
• Morphing (innerMorph/outerMorph) preserves animations better than innerHTML/outerHTML

Form Data Not Included

• GET and DELETE requests do NOT include enclosing form data by default in htmx 4
• Fix: add hx-include="closest form" to include form values
• Non-GET/DELETE requests (POST, PUT, PATCH) DO include enclosing form values automatically
• Check hx-vals syntax: it takes HCON (key:value, other:2), which also accepts JSON. Use the js: prefix for dynamic values

htmx 2 Code Not Working in htmx 4

Quick compatibility fixes:

1. Add htmx.config.implicitInheritance = true (restores automatic inheritance)
2. Add htmx.config.noSwap = [204, 304, '4xx', '5xx'] (restores htmx 2 swap behavior)
3. Replace hx-ext="name" with <script src="ext.js">. The extensions config is an optional whitelist, not a requirement
4. Update event names: htmx:beforeRequest -> htmx:before:request, htmx:afterSwap -> htmx:after:swap, etc.
5. Replace hx-disabled-elt -> hx-disable
6. Replace hx-disable (old meaning of ignoring) -> hx-ignore
7. Replace hx-vars -> hx-vals with js: prefix
8. Load the hx-prompt extension to keep hx-prompt working
9. Or load the htmx-2-compat extension for gradual migration

Browser DevTools Techniques

Network Tab

• Filter by Fetch/XHR requests
• Look for HX-Request: true in request headers to confirm htmx is making the request
• Check response headers for HX-Trigger, HX-Retarget, HX-Reswap
• Check response body -- should be HTML, not JSON

Elements Panel

• Inspect element and check for _htmx property (indicates htmx processed it)
• Look for htmx-request class during active requests
• Look for htmx-swapping / htmx-settling classes during swaps

Console

• htmx.config.logAll = true -- log every event (errors and warnings already on by default)
• htmx.version -- confirm which major version is loaded
• htmx.find("#selector") -- test extended CSS selectors
• htmx.trigger(elt, "eventName") -- manually fire events

Instructions for Claude

When helping users debug htmx issues:

1. Ask about the htmx version first -- htmx 2 vs 4 is the most common source of confusion
2. Suggest htmx.config.logAll = true as the first step and ask for console output (errors/warnings are visible without it)
3. Check for :inherited modifier when inheritance problems are reported
4. Check the Network tab -- verify the request is being made and inspect the response
5. Check the response body -- it should be HTML, not JSON
6. Look for typos in attribute names (e.g. hx-triger instead of hx-trigger)
7. Check hx-status attributes that might override swap behavior for specific status codes
8. Verify the server returns appropriate status codes (200 for success, 422 for validation errors, 204 for no-content)