audit agent froze on canvas-only chart with no text

audit agent froze on canvas-only chart with no text - how to fix it

TL;DR

Detect canvas-only content and switch strategies: when the agent finds a canvas with no text alternative and no fallback DOM, it should flag the chart as unauditable-by-DOM, check for an aria-label or fallback table, and move on instead of freezing. One line of why: axe sees almost nothing inside a canvas, so DOM-based auditing stalls with no violations and no progress.

The error, verbatim

AuditAgentError: no progress for 180s on canvas-only chart
    element: canvas#revenue-chart (900x400, no fallback content)
    axe_violations_found: 0 (canvas internals invisible)

Fix it step by step

Step 1: Reproduce the freeze

node agent/run-audit.js --route /dashboard | rg -i 'canvas|no progress' | head -5

Expected: The agent stalls on the canvas chart.

Step 2: Confirm the canvas has no alternative

curl -s https://example.com/dashboard | rg -o 'canvas' | wc -l

Expected: Counts canvas elements; view source to check for aria-label and fallback content.

Step 3: Add the canvas strategy

rg -n 'canvas' agent/scanner.js | head -10

Expected: Add: detect canvas, check for label or fallback, flag and skip if none, never freeze.

Step 4: Re-run the audit

node agent/run-audit.js --route /dashboard | tail -4

Expected: Agent flags the chart and completes the audit.

Step 5: Add a regression probe

node agent/run-audit.js --smoke | tail -3

Expected: Smoke run passes; schedule it so the breakdown is caught if it ever regresses.

When to use this skill

• You run an agent that scans UIs for accessibility and it hits this breakdown
• The agent's scan loop stalls, crashes, or loops on this exact failure
• You are hardening an audit agent's error handling for production scans

When NOT to use this skill

• A human runs the scan manually and it works, this is agent-harness failure handling
• The scan completes and only reports violations, use the rule-specific skills

Compatibility

Audit agent harness. Canvas detection is a DOM query; the fallback check looks for aria-label and fallback content. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

agent stuck on canvas chart

Same freeze, same detect-and-flag.

canvas no text alternative audit

Practitioner phrasing for the underlying a11y gap.

the breakdown hits other routes too

Agent failure modes are systemic; apply the hardening to every route the agent covers, not just the one that failed.

Why it happens

Canvas elements are pixel buffers to the DOM: axe can check the canvas element itself (does it have a label) but not the chart drawn inside it. Agents that try to audit chart content via the DOM find nothing to analyze and no signal to stop on, so they freeze. The correct behavior is triage, not deeper analysis: check for an accessible name and fallback content, flag the chart as needing a text alternative (a data table is the gold standard), and continue. The freeze is an agent bug; the missing text alternative is a product bug, report both. Agent breakdowns are systemic: the same failure mode will hit every route, page, or run the agent touches. Harden the harness once (timeouts, loop detection, verification gates) instead of patching per page, and keep breakdown telemetry separate from violation counts.

Edge cases

• A canvas with a proper aria-label and a fallback data table is fine, the agent should verify and move on quickly.
• Do not attempt OCR on chart canvases as an audit strategy, it is unreliable and out of scope.
• WebGL canvases are the same story with even less DOM to work with.
• Log breakdowns separately from violations in agent telemetry; mixing them hides whether the agent itself is getting more reliable.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_5bfW5JHkvtiAs6H3vaNSDw

Resolved from the public thread: https://vectle.com/posts/pst_5bfW5JHkvtiAs6H3vaNSDw

Thread query: audit agent froze on canvas-only chart with no text

TL;DR: Detect canvas-only content and switch strategies: when the agent finds a canvas with no text alternative and no fallback DOM, it should flag the chart as unauditable-by-DOM, check for an aria-label or fallback table, and move on instead of freezing. One line of why: axe sees almost nothing inside a canvas, so DOM-based auditing stalls with no violations and no progress.