What causes "[impeccable] scan failed" in pbakaus/impeccable?

Inspect the logged err object for the root cause.

[impeccable] scan failed

Error message

[impeccable] scan failed

What it means

Warning emitted when the automatic impeccable scan throws at startup. The auto-scan runs 100ms after DOMContentLoaded (or page load if already loaded) and catches any synchronous error so a broken page never breaks the host site. The scan produces no or partial results.

Source

Thrown at crates/live/assets/detect-antipatterns-browser.js:3813

      if (e.data.action === 'remove') {
        clearOverlays();
        ui.remove();
      }
      if (e.data.action === 'highlight') {
        ui.highlightSelector(e.data.selector);
      }
      if (e.data.action === 'unhighlight') {
        ui.unspotlight();
      }
    });
    window.postMessage({ source: 'impeccable-ready' }, '*');
  } else {
    if (window.__IMPECCABLE_CONFIG__?.autoScan !== false) {
      const runAutoScan = () => {
        try {
          scan();
        } catch (err) {
          console.warn('[impeccable] scan failed', err);
        }
      };
      if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', () => setTimeout(runAutoScan, 100));
      } else {
        setTimeout(runAutoScan, 100);
      }
    }
  }

  window.impeccableDetect = detect;
  window.impeccableDetectAsync = detectAsync;
  window.impeccableScan = scan;
  window.impeccableScanAsync = scanAsync;
  // Raw measurement for the URL engine's content-hidden-at-rest pass: it
  // drives a reveal sweep from Node and thresholds the result itself.
  window.impeccableMeasureHiddenText = () => JSON.parse(__impeccable.measure_hidden_text());
  window.impeccableCollectVisualContrastCandidates = collectVisualContrastCandidates;

View on GitHub (pinned to 2bc2879276)

Solutions

Inspect the logged err object for the root cause.
Set window.__IMPECCABLE_CONFIG__ = { autoScan: false } before the script loads to disable auto-scan, then trigger scans manually.
Rebuild/refresh the detector bundle (cargo xtask bundle) if the asset is stale, and verify the page in a clean profile.

Example fix

// before (fail at startup, page breaks)
scan();
// after (guarded auto-scan)
try { scan(); } catch (err) { console.warn('[impeccable] scan failed', err); }

Defensive patterns

Strategy: try-catch

Validate before calling

if (window.__IMPECCABLE_CONFIG__?.autoScan === false) return; // auto-scan disabled by page

Type guard

function scanable() { return typeof window.scan === 'function' && document.readyState !== 'loading'; }

Try / catch

const runAutoScan = () => {
  try { scan(); } catch (err) { console.warn('[impeccable] scan failed', err); }
};
document.readyState === 'loading'
  ? document.addEventListener('DOMContentLoaded', () => setTimeout(runAutoScan, 100))
  : setTimeout(runAutoScan, 100);

Prevention

Always wrap auto-init scripts in try/catch so host pages never break.
Defer scanning ~100ms past DOMContentLoaded, as the bundle does, to avoid half-built DOM.
Test the injected script on hostile pages (heavy frameworks, other extensions) before release.

When it happens

Trigger: window.__IMPECCABLE_CONFIG__.autoScan is not false and the injected scan() throws synchronously during the deferred auto-run (DOM mutation during scan, unsupported selectors, or an engine/rule bug).

Common situations: Pages with unusual DOM (huge tables, broken custom elements), conflicts with other extensions injecting scripts, or a stale/mismatched detector bundle.

Related errors

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/ba6c9840c9661b07. Report an issue: GitHub.