pa11y error ssl certificate failed on staging url

pa11y error ssl certificate failed on staging url - how to fix it

TL;DR

Tell Chromium to accept the staging certificate: pass --chrome-flags with --ignore-certificate-errors, or better, fix the staging cert. Self-signed and expired certs on staging are the norm, and pa11y's browser refuses them by default. One line of why: pa11y is a browser, and browsers distrust bad certs, so the scan never starts.

The error, verbatim

Error: SSL certificate failed for https://staging.example.com/
    net::ERR_CERT_AUTHORITY_INVALID

Fix it step by step

Step 1: Reproduce the cert error

npx pa11y https://staging.example.com/ | rg -i 'ssl|cert' | head -3

Expected: The SSL certificate error repeats.

Step 2: Inspect the certificate

echo | openssl s_client -connect staging.example.com:443 -servername staging.example.com | openssl x509 -noout -issuer -dates

Expected: Shows the issuer and dates; self-signed or expired confirms the staging-cert story.

Step 3: Bypass for staging scans

npx pa11y https://staging.example.com/ --chrome-flags='--ignore-certificate-errors' --reporter cli | tail -3

Expected: Scan runs past the cert error and reports real violations.

Step 4: Persist in CI config

node -e "const fs=require('fs'); const c=JSON.parse(fs.readFileSync('.pa11yci.json','utf8')); c.defaults=c.defaults||{}; c.defaults.chromeFlags=['--ignore-certificate-errors']; fs.writeFileSync('.pa11yci.json', JSON.stringify(c,null,2)); console.log('saved')"

Expected: The bypass is saved for staging runs only.

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

pa11y 6.x / pa11y-ci 3.x. The --chrome-flags passthrough controls Chromium behavior. Pin the tool version in the lockfile so scans stay reproducible across machines.

Variant phrasings

pa11y ssl certificate failed staging

Same error, same bypass.

pa11y errcertauthority_invalid

The underlying Chromium error, same fix.

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

Staging environments use self-signed certificates, internal CAs, or expired certs, and Chromium (which pa11y drives) rejects them with ERRCERTAUTHORITYINVALID or ERRCERTDATEINVALID. The scan fails before any audit runs. The bypass flag is appropriate for staging scans in CI, but the real fix for a long-lived staging environment is a proper certificate from an internal CA the CI trust store knows. 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

• Only bypass certs for staging and dev scans, never for production URLs.
• If staging uses an internal CA, add the CA to the CI trust store instead of bypassing, it is barely more work.
• Expired certs on staging still deserve a ticket, the bypass hides the rot.
• 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/pst__SJbzJ-39LtviSjGOnG9dw