axe-core runpartial error incomplete results bug

axe-core runpartial error incomplete results bug - how to fix it

TL;DR

Call the rest of the partial-run protocol: runPartial returns partial results plus an unfinished context, and you must feed both back into the next run until axe reports completion. Treating the first result as final is the bug. One line of why: runPartial exists to split big analyses across frames or time slices, and the results are meaningless until the protocol completes.

The error, verbatim

Error: axe.runPartial returned incomplete results; analysis did not finish
    at runA11yPartial (scripts/audit.js:44:11)
    axe-core 4.8.1

Fix it step by step

Step 1: Reproduce the partial run

node scripts/audit.js | rg -i 'partial|incomplete' | head -5

Expected: The incomplete-results error repeats.

Step 2: Inspect the protocol loop

rg -n 'runPartial|finishRun' scripts/audit.js | head -10

Expected: Shows whether the code loops runPartial to completion with finishRun, or stops after one call.

Step 3: Complete the loop

node scripts/audit.js | tail -5

Expected: After implementing the runPartial/finishRun loop, the script reports complete results.

Step 4: Verify result completeness

node -e "const r=require('./audit-out.json'); console.log('violations:', r.violations.length, 'incomplete:', !!r.incomplete)"

Expected: violations is populated and incomplete is empty or absent.

Step 5: Re-run twice to rule out flakes

npx pa11y https://example.com/ | tail -2

Expected: Two consecutive clean runs before calling it fixed; scan tools flake under load, so one green run is not proof.

When to use this skill

• The scan tool itself fails or crashes instead of reporting violations
• Your a11y CI step errors out before any rule results appear
• You run this tooling (pa11y, lighthouse, cypress-axe, axe-playwright) in automation

When NOT to use this skill

• The tool runs fine and reports real violations, use the rule-specific skills instead
• The failure is in your app code, not the scanner

Compatibility

axe-core 4.8+ (runPartial/finishRun API). Used for cross-frame and chunked analyses. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

axe runpartial incomplete results

Same error, same protocol fix.

axe finishrun missing

Practitioner phrasing: the loop never calls finishRun.

same failure locally and in CI

Scan tool failures are environmental; a fix that works on a laptop must also be verified under CI conditions.

Why it happens

axe.runPartial is designed for splitting analysis across iframes or async chunks: each call returns partial results and context for the next call, and axe.finishRun assembles the final result. Code that calls runPartial once and reads the results gets an incomplete analysis by design. The error surfaces when the caller treats partial output as final. The fix is the documented loop: keep calling runPartial with the returned context until it signals completion, then finishRun. Scan tool failures are environmental more often than not: memory, network, certificates, and browser state. When a fix works locally, verify it under CI conditions too, because CI runners are slower, more locked down, and run things in parallel.

Edge cases

• Do not use runPartial for simple single-page audits, axe.run is simpler and complete in one call.
• Each iframe needs its own runPartial pass with its context merged, that is the API's main use case.
• Partial results are not comparable across runs, only the finished result is stable.
• Record the working flags in CI config or a runbook; the fix evaporates if it only lives in one person's shell history.

Provenance

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

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

Thread query: axe-core runpartial error incomplete results bug

TL;DR: Call the rest of the partial-run protocol: runPartial returns partial results plus an unfinished context, and you must feed both back into the next run until axe reports completion. Treating the first result as final is the bug. One line of why: runPartial exists to split big analyses across frames or time slices, and the results are meaningless until the protocol completes.