pbakaus/impeccable · warning

[impeccable] scan failed

Error message

[impeccable] scan failed

What it means

The Impeccable browser bundle wraps its automatic initial scan() call in a try/catch and logs '[impeccable] scan failed' via console.warn instead of throwing. It indicates the static/scan pass crashed at runtime (e.g. a DOM query or rule threw) while loading the page; auto-scan is best-effort and never breaks the page.

Source

Thrown at browser-bundle/50-scan.js:423

      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

1. Read the accompanying error object in the console warn; it names the rule or line that threw
2. Set window.__IMPECCABLE_CONFIG__ = { autoScan: false } to disable the automatic scan if it is disruptive
3. Update the extension/bundle to the latest ENGINE_VERSION, as scan crashes are usually fixed in newer rule code
4. Reproduce with the page's scripts disabled to determine whether page mutations race the scan

Example fix

// before
window.__IMPECCABLE_CONFIG__ = {};
// after
window.__IMPECCABLE_CONFIG__ = { autoScan: false }; // opt out of auto scan; call scan() manually

if (window.__IMPECCABLE_CONFIG__?.autoScan === false) { /* auto-scan disabled; skip */ }

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

try { scan(); } catch (err) { console.warn('[impeccable] scan failed', err); /* non-fatal: page continues */ }

When it happens

Trigger: autoScan is not disabled in window.__IMPECCABLE_CONFIG__ and the runAutoScan wrapper (scheduled 100ms after DOMContentLoaded, or 100ms after script eval if the DOM is already ready) invokes scan() and scan() throws.

Common situations: A page with unusual DOM (detached nodes, shadow DOM, non-standard APIs) causing a rule to throw; a broken or partially-loaded detector bundle interacting with page scripts that mutate the DOM during the scan; an older browser lacking APIs the scanner assumes.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• [impeccable] visual contrast scan failed
• [impeccable] scan failed
• Live browser script part missing: ${part.name} (${part.path}
• ${cap.error}
• [impeccable] visual contrast scan failed

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