Troubleshooting

How to use this page

Find the symptom that matches what you see, follow the steps, then run the check at the end of the section. Most start-up errors come from switching between Node.js versions. To get more detail from a failing run, set OOBEE_VERBOSE before you run the scan:

export OOBEE_VERBOSE=1Copy to clipboardErrorCopied

On Windows PowerShell, use $env:OOBEE_VERBOSE=1.

Scan fails with a syntax error on start

Symptom: The scan stops at once with a SyntaxError: Invalid regular expression, naming a long URL pattern.

Cause: The Node.js version is older than 20.

Steps:

1. Check the version with node -v.
2. Install Node.js 20 (LTS) or later. Refer to Install Oobee manually.

Check: node -v shows version 20 or later and the scan starts.

Scan fails after switching Node.js versions

Symptom: The scan stops with an error that says a module “was compiled against a different Node.js version” and names two NODE_MODULE_VERSION numbers.

Cause: The installed packages were built for a different Node.js version than the one now in use.

Steps:

1. In the Oobee folder, run npm rebuild.
2. If the error remains, run npm install.

Check: The scan starts without the module error.

Scan exits without an error

Symptom: The terminal prints the npm run cli line and then returns to the prompt, with no scan and no message.

Steps:

1. Delete the node_modules folder, then run npm install.
2. Set OOBEE_VERBOSE as shown at the top of this page.
3. Run the scan again.
4. If it still exits, find the log file. It is named <UUID>.txt. Refer to CLI options, environment variables and error codes for its location.

Check: The terminal prints “Starting scan…”. If it does not, report the problem. Refer to Get more help at the end of this page.

URL check fails before the scan starts

Symptom: Oobee prints a message such as “URL cannot be accessed. Please verify whether the website exists.” and stops, with an exit code of 11 or higher.

Steps:

1. Look up the message and code in the URL validation table in CLI options, environment variables and error codes.
2. Apply the check in the last column of that table.
3. For code 16 “Login required”, send credentials. Refer to Scan pages behind a login.

Check: The scan prints “Starting scan…” instead of the error.

Pages are skipped with 403 or other HTTP errors

Symptom: The report lists many pages under Pages Not Scanned with reasons such as “403 - Forbidden”, “429 - Too Many Requests” or “Web Crawler Errored”.

Cause: The site’s firewall or rate limiter blocks fast automated requests. This is common on large scans and on data-centre addresses.

Steps:

1. Lower the number of pages scanned at once, for example -t 1.
2. Raise the time limit with -l <SECONDS>, or leave it at the default of no limit.
3. Use -s same-hostname so that Oobee does not spend time on other subdomains.
4. Run the scan from a network that the site does not block. Data-centre addresses are more likely to be rate-limited than home or office addresses.

Oobee already halves its concurrency on each 403 or 429, and tries the page once more later. Refer to How Oobee scans.

Check: Fewer pages appear under Pages Not Scanned in the new report.

Scan finds fewer pages than expected

Symptom: The scan finishes with a low “Pages Scanned” count.

Steps:

1. Check whether the scan stopped at the page limit. Raise -p if so. The default is 100.
2. Check whether the scan stopped at the time limit set with -l, or by OOBEE_MAX_SCAN_MINUTES.
3. For a live site, use the intelligent scan type instead of website. Refer to Run a scan.
4. For pages behind a login, send credentials. Refer to Scan pages behind a login.

Check: The “Pages Scanned” count rises, or the report shows the reason for each page that is not scanned.

Pages time out on a slow machine

Symptom: Pages that load on a fast machine are recorded as errors, or results differ between runs.

Cause: Oobee gives each page 30 seconds to start loading and 90 seconds in total. A slow or throttled processor can run out of time or check a page before it has finished rendering.

Steps:

1. Run on a machine with dedicated processor cores and cooling. Laptops that overheat get slower during long scans.
2. Lower concurrency with -t 10.
3. In Docker, give the container enough processor and memory, and avoid thin-provisioned storage.

Check: Fewer pages are recorded as “Web Crawler Errored”.

Scan stops with a disk space error

Symptom: The scan fails with ENOSPC or a “no space left” message part-way through.

Cause: Large scans create large temporary and report files.

Steps:

1. Free disk space. A 1,000-page scan needs about 5 to 10 GB free, and a 5,000-page scan needs at least 20 GB.
2. Turn off element screenshots with -a none to cut the size of the results.

Check: The scan completes and writes report.html.

PDF scan fails or PDFs are skipped

Symptom: The log says “Could not find veraPDF executable”, or PDFs do not appear in the report.

Steps:

1. Use the portable Oobee, which includes VeraPDF, or install VeraPDF and add it to your PATH. Refer to Install Oobee manually.
2. Check that verapdf --version runs.
3. Add -i all or -i pdf-only to the scan. The default, html-only, skips PDFs. Refer to Scan PDFs and local files.

Check: The report lists the PDF files under Pages Scanned.

Custom flow does not open a browser

Symptom: A custom flow scan does not start, or the browser window does not appear.

Cause: More than one Playwright version is installed, so the browser files do not match.

Steps:

1. Delete the Playwright browser cache folder. On Windows it is %USERPROFILE%\AppData\Local\ms-playwright. On macOS it is ~/Library/Caches/ms-playwright.
2. In the Oobee folder, reinstall the browsers by running npx playwright install. This installs the browsers for the Playwright version in package.json. The README gives an old pinned version, npx playwright@1.27.1 install, which does not match the current version.
3. Run the custom flow scan again. Refer to Scan a user flow with custom flow.

Check: A browser window opens with the Oobee toolbar.

Element screenshots are missing

Symptom: Some issues in the report have no screenshot.

Cause: Oobee tries for 5 seconds to find and capture an element. An animated element, such as a carousel, can move out of view and time out.

Steps: No fix is known for animated elements. Check the element in the browser by hand, using the HTML snippet and the XPath in the report.

Check: Not applicable.

Report is missing or incomplete

Symptom: report.html or summary.pdf is not in the results folder.

Steps:

1. Look in the right folder. Results go to results in the folder where you ran the scan, to the -e folder, or to an Oobee folder in your Documents or home folder if the first one was not writable. Refer to Read and export scan reports.
2. For a missing summary.pdf, check that a supported browser is installed. Oobee needs a browser to make the PDF.

Check: The results folder contains report.html, summary.pdf and report.csv.

Scan results seem wrong for pages with heavy scripts

Symptom: Results change between runs, or issues are missing on a page that loads content late.

Cause: Oobee scans after the page settles, but late changes can come after the check.

Steps:

1. Run the scan again on a faster machine.
2. For one page, use a custom flow scan, wait for the page to finish loading, then select Scan page.

Check: Repeated scans of the same page give the same results.

Get more help

If a problem remains after these steps, open an issue on the Oobee issue tracker. Include:

• The steps that led to the problem.
• The command you ran, without credentials.
• The Oobee version, shown on the “Oobee version” line when a scan starts.
• The log file, <UUID>.txt, from a run with OOBEE_VERBOSE set.

To report a security vulnerability, use the GovTech Vulnerability Disclosure Programme.