Accessibility Scanner: Troubleshooting Guide

This guide explains common errors you might encounter while using the Accessibility Scanner, their likely causes, and suggested solutions using the scanner's UI options. It's important to distinguish between errors originating from the scanner setup/environment and errors originating from the website being scanned.

Installation: 

⚠️ Please Note: Depending on your security settings, the installer may be blocked. If this happens, simply right-click the "Scanner Installer," select Properties, and at the bottom of the window, check Unblock, then click OK.

🪪 Why isn’t the .exe file signed? Code signing is not currently a priority. While signing an executable can improve trust on Windows, obtaining a certificate typically costs $100/year or more. Even with a valid certificate, Windows SmartScreen and antivirus software can still flag the file.

Ultimately, the most reliable way to reduce warnings is reputation: once the program has been downloaded and used by enough people, Windows will treat it as more trustworthy over time, regardless of signing.

Caveats: 

💾 Axe-Scanner can only perform as well as your computer allows. If your internet connection is poor or your system is slow, scans may take longer and perform worse. This could result in skipped pages, missing content, or other issues.

System Recommendations

📡 Accessibility Scanner v3.8.0: The Complete Troubleshooting Guide

This guide provides a comprehensive breakdown of common issues, error messages, and their solutions. By understanding the cause of a problem, you can use the scanner's powerful configuration options to resolve it.

First Step for Any Issue: Always check both the UI Activity Log and the backend Node.js console (the terminal where you started the scanner) for the most detailed error messages.

1. Navigation, Connection & Page Load Errors

These are the most common errors, occurring when the scanner's browser fails to load a URL.

Symptoms:

• The scan fails immediately or on specific pages.
• UI Activity Log Messages:
  • Navigation timeout of [X] ms exceeded
  • net::ERR_CONNECTION_REFUSED, net::ERR_NAME_NOT_RESOLVED
  • net::ERR_PROXY_CONNECTION_FAILED
  • HTTP Status Errors (e.g., status code 403, 404, 500, 503)
  • Navigation failed because browser has disconnected!
  • Messages indicating a page is not HTML (if "Skip pre-scan content check" is off).

Cause 1.A: Simple Configuration or Network Issue

• Possible Reasons:
  • Incorrect URL: A typo in the URL, or missing http:// or https://.
  • Network Problem: Your local internet, VPN, or a corporate firewall is blocking access.
  • Proxy Issue: The "Proxy Server URL" is incorrect, or the proxy itself is down.
  • Target Site Down: The website is genuinely offline.
• Solutions:
  • Verify URLs: Manually copy and paste every URL from your configuration (Start URL, Login URL, Sitemap, etc.) into a regular browser on the same machine to confirm they work.
  • Check Your Network: Disable your VPN temporarily to see if it's the cause. Check your local firewall and antivirus software settings.
  • Isolate Proxy: If using a proxy, try the scan without it. Verify the proxy URL and port are correct.

Cause 1.B: Target Website is Slow (Timeouts)

• Possible Reasons:
  1. The page has many large resources, complex scripts, or a slow backend, causing it to take longer to load than the scanner's configured timeout.
• Solutions:
  1. Increase Navigation Timeout:
     • Location: Advanced Scan Options -> Scan Behaviour -> Navigation Timeout (ms).
     • Action: Increase this value significantly (e.g., from 90000 to 120000).
  2. Increase Other Timeouts (if needed):
     • Location: Backend Fine-Tuning (Advanced)
     • Action: For crawl-specific timeouts, increase Crawl Page Navigation Timeout (ms). For general pre-scan checks, increase General Request Timeout (ms).

Cause 1.C: Target Website is Blocking the Scanner (403, 429, CAPTCHAs)

• Possible Reasons:
  1. The website's Web Application Firewall (WAF) or anti-bot system has detected the automated nature of the scan and is actively blocking your requests. This is a very common scenario on modern websites.
• Solutions (Apply in this order):
  1. Use the "Analyse Site Settings" Button: This is your most important first step. It runs a quick check and will often detect common protection mechanisms, automatically suggesting the best settings to use.
  2. Enable Stealth Modes:
     • Location: Advanced Scan Options -> Other Options
     • Action: Start by checking "Basic Stealth Mode?". If issues persist, uncheck it and check "Enhanced Stealth & Fingerprint Spoofing?" instead.
  3. Drastically Reduce Speed and Increase Delays:
     • Location: Crawl Options
     • Action: Set "Crawl Delay (ms)" to a high value (e.g., 2000 to 5000).
     • Location: Advanced Scan Options -> Other Options
     • Action: Ensure "Enable Adaptive Network Delay?" is checked. This allows the scanner to intelligently slow down when it detects resistance.
  4. Disable All Parallelism:
     • Action: Uncheck "Enable Parallel Crawling?" and "Enable Parallel Axe Scanning?". This makes your scan appear like a single, slow user, which is much less likely to be flagged.
  5. Use a Proxy:
     • Location: Advanced Scan Options -> Other Options -> Proxy Server URL
     • Action: If your direct IP is blocked, routing traffic through a proxy is essential.
  6. Contact Site Administrators: For legitimate audits, the most reliable solution is to ask the website's administrators to whitelist your IP address.

2. Axe Scan Errors & Page-Specific Issues

These errors occur during the accessibility analysis phase on a specific page.

Symptoms:

• A scan completes, but the report shows "Page Scan Errors" for certain URLs.
• UI Activity Log Messages:
  • Axe execution timed out after [X]ms.
  • Axe script did not load successfully...
  • Scan Error: [Specific JavaScript error]
  • JS error on scan task page [URL]... (often indicates an error in the target page's code).

Cause 2.A: Issues with the Target Page Itself

• Possible Reasons:
  1. Page JavaScript Errors: Errors in the scanned page's own code are interfering with Axe's execution.
  2. Extremely Complex/Large DOM: The page is so large and complex that Axe cannot finish its analysis within the configured time.
  3. Content Security Policy (CSP): The website has a strict security policy that blocks the injection of the Axe-core script.
• Solutions:
  1. Increase Axe Timeout:
     • Location: Backend Fine-Tuning (Advanced) -> Timeout Settings -> Axe Execution Timeout (ms)
     • Action: If you suspect complex pages are the issue, increase this value (e.g., from 45000 to 60000).
  2. Handle Content Security Policies:
     • Location: Advanced Scan Options -> Other Options
     • Action: Check the box for "Attempt to Handle Trusted Types?". This uses an alternative injection method.
  3. Exclude Problematic Sections:
     • Location: Advanced Scan Options -> Axe Configuration -> Exclude CSS Selectors
     • Action: If you know a specific part of the page (like a third-party widget) is causing errors, add its CSS selector here to tell Axe to ignore it.
  4. Report Website Bugs: If the UI log shows JavaScript errors originating from the page (and not from the scanner), this is a bug in the website itself that should be reported to its developers.

3. Parallel Processing & Cluster Errors

These errors are specific to using "Enable Parallel Crawling?" or "Enable Parallel Axe Scanning?".

Symptoms:

• The scan seems to hang or stall, especially near the end.
• UI Activity Log Messages:
  • Cluster task error crawling [URL]...
  • Attempted to use detached Frame...
  • Cluster closed unexpectedly...
  • The backend console may show an error like Cluster idle() timed out....

Cause 3.A: System Resource Overload or Race Conditions

• Possible Reasons:
  1. The selected Concurrency value is too high for your machine's RAM or CPU, causing browser workers to crash.
  2. When stopping a scan or hitting the crawl limit, there can be a race condition where workers try to operate on pages that the main controller is already shutting down.
• Solutions:
  1. Reduce Concurrency: This is the most effective solution.
     • Location: Crawl Options and Axe Scan Rules sections.
     • Action: Lower the "Crawl Concurrency" and/or "Scan Concurrency" values. Start with 2 and see if the scan is stable before increasing.
  2. Disable Parallelism: For maximum stability, especially when diagnosing an issue, uncheck both parallel options and run the scan sequentially.
  3. Isolate the Problem: Try enabling only one parallel mode at a time (e.g., only "Parallel Crawling?") to determine which phase is causing instability.
  4. Monitor System Resources: Use your computer's Task Manager (Windows) or Activity Monitor (macOS) to watch CPU and RAM usage during a parallel scan. If they are pegged at 100%, your concurrency is too high.

4. System & Resource Exhaustion Issues

These issues manifest as general scanner slowness, frequent crashes, or the entire application becoming unresponsive.

Symptoms:

• The application becomes very slow over time.
• The "Backend Memory Usage" in the UI climbs continuously to very high numbers (e.g., > 1-2 GB).
• Your computer's fans spin up, and the whole system becomes sluggish.
• The backend console shows errors like Network.[Command] timed out. Increase the 'protocolTimeout' setting....

Cause 4.A: Scan Configuration is Too Demanding for Your Hardware

• Possible Reasons:
  1. Using "Per Instance" screenshots on a very large crawl is the most common cause, as it stores thousands of images in memory.
  2. High concurrency settings combined with a large Max Crawl Size.
  3. A very long-running sequential scan without browser restarts enabled.
• Solutions:
  1. Adjust Screenshot Settings:
     • Location: General Behaviour & Output
     • Action: Switch Screenshot Mode to "Per Issue Type (Lower Memory)" or disable screenshots entirely.
  2. Reduce Parallelism: As described in Section 3, disable parallel modes or lower concurrency.
  3. Limit the Scan Scope:
     • Location: Crawl Options
     • Action: Set a reasonable "Max Crawl Size" (e.g., 500) and/or use "Max Crawl Depth".
  4. Ensure Browser Restarts are Enabled:
     • Location: Advanced Scan Options -> Scan Behaviour
     • Action: For sequential scans, ensure "Enable Periodic Browser Restarts" is checked. This is a critical stability feature.
  5. Increase Protocol Timeout (Last Resort):
     • Location: Backend Fine-Tuning (Advanced)
     • Action: If you are certain resources are not the issue, but you see protocolTimeout errors, you can cautiously increase the "Puppeteer Protocol Timeout (ms)". This often masks an underlying resource problem.

5. Other Specific Issues

• PDF Check Errors:
  • Symptom: The report or log shows errors like "Failed PDF check" or "Content-Type not 'application/pdf'".
  • Solution: These errors almost always indicate a problem with the linked PDF on the target website (it's missing, protected, or not a real PDF). Verify the link manually. These errors do not affect the HTML page scans. You can disable the check in Advanced Scan Options.
• Configuration Errors (UI Validation):
  • Symptom: An error message appears directly below an input field, and the "Start Scan" button does not work.
  • Solution: Correct the value in the highlighted field. This is the UI preventing you from sending an invalid request to the backend. Common mistakes are missing http:// or entering non-numeric characters in a number field.
• Global Errors (UNHANDLED REJECTION in Console):
  • Symptom: The scan abruptly stops, and the backend Node.js console shows a severe error message and a "stack trace".
  • Solution: This indicates a potential bug in the scanner's code. Please copy the entire console output, your scan configuration (using the "Shareable Scan Configuration" feature), and a description of the target site, and report it to the developer.