pbakaus/impeccable · error · Error

${cap.error}

Error message

${cap.error}

What it means

impeccableDetectFromSnapshot wraps a snapshot capture plus WASM analysis; if the underlying __impeccableSnapshot.capture() step fails it returns {error}, and this wrapper re-throws that error string verbatim as an Error. The cap.error text describes why the page snapshot could not be captured or processed.

Source

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

  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;
  window.impeccableAnalyzeVisualContrast = analyzeVisualContrast;
  window.impeccableGetLastVisualContrastAnalyses = () => lastVisualContrastAnalyses.slice();

  // The snapshot route (what the extension runs when the page's CSP keeps
  // WebAssembly out of every world it can reach), exposed here so the two
  // routes can be A/B'd on the same page: capture, run the same core over
  // the snapshot (answering its hit-test needs from the live page), and
  // serialize through it. Deterministic findings only; the visual-contrast
  // pass over a snapshot is the extension's (see 60-offscreen.js).
  window.impeccableSnapshotCapture = (options) => __impeccableSnapshot.capture(options);
  window.impeccableDetectFromSnapshot = function (options = {}) {
    const t0 = performance.now();
    const cap = __impeccableSnapshot.capture(options);
    if (cap.error) throw new Error(cap.error);
    const t1 = performance.now();
    let out = JSON.parse(__impeccable.collect_findings_from_snapshot(cap.json, collectConfigJson()));
    let rounds = 1;
    while (out.needs) {
      __impeccable.snapshot_add_facts(JSON.stringify(__impeccableSnapshot.answer(out.needs, cap)));
      out = JSON.parse(__impeccable.collect_browser_findings(collectConfigJson()));
      if (__impeccable.snapshot_has_needs()) out = { needs: JSON.parse(__impeccable.snapshot_take_needs()) };
      rounds++;
    }
    const serialized = JSON.parse(__impeccable.serialize_findings(JSON.stringify(out.groups)));
    const unknownStyleProps = JSON.parse(__impeccable.snapshot_unknown_style_props());
    __impeccable.snapshot_clear();
    return {
      findings: serialized,
      pageLevel: out.pageLevel,
      stats: { ...cap.stats, rounds, unknownStyleProps, captureMs: t1 - t0, coreMs: performance.now() - t1 },
    };
  };

View on GitHub (pinned to 2bc2879276)

Solutions

1. Read the thrown message: it is the raw capture error, and fix the specific capture problem it names
2. Ensure the core/agent script is fully initialized before calling impeccableDetectFromSnapshot
3. Call it only on top-level, fully loaded documents
4. Wrap in try/catch and fall back to impeccableDetectAsync if snapshot-based detection is optional

Example fix

// before
const findings = impeccableDetectFromSnapshot();
// after
let findings;
try { findings = impeccableDetectFromSnapshot(); }
catch (e) { console.warn('snapshot capture failed:', e.message); findings = null; }

function canDetectFromSnapshot() {
  return typeof window.impeccableDetectFromSnapshot === 'function' &&
    document.readyState === 'complete';
}

try {
  const out = impeccableDetectFromSnapshot(options);
} catch (e) {
  console.warn('impeccable snapshot detect failed:', e.message);
  // fall back to impeccableDetectAsync or skip
}

When it happens

Trigger: Calling window.impeccableDetectFromSnapshot(options) when capture(options) returns an error field — e.g. the document is in a non-capturable state, the DOM snapshot builder threw, or the core module is unavailable.

Common situations: Calling detect-from-snapshot on pages where capture is unsupported (about:blank, cross-origin frames, detached documents); racing the call before the core finishes loading.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Live browser script part missing: ${part.name} (${part.path}
• snapshot did not parse
• [impeccable] the offscreen document has no live page; load a
• [impeccable] scan failed
• ambiguous snapshot slug; use an explicit ./path or remove th

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