Troubleshooting Guide

Report a bug

1. In the footer of the scanning interface, select Options, then Report Bug.
2. Select Open email. Your email app opens a message to support@octopusscanner.com with a template that already includes the app version, your platform, the browser or runtime in use, and the last scan ID if there is one. If you have no email app set up, select Copy address and Copy template instead and paste them into any email service.
3. If the problem concerns a scan that produced a report, open that HTML report, select Export Bug Data in its action bar, and attach the downloaded JSON file.
4. If the engine stopped unexpectedly, attach its crash file too. See below.
5. Review the message, then send it. Nothing is attached or sent automatically.

Crash files record the last log lines before something stopped unexpectedly:

• macOS: When the engine stops with an error, Octopus Scanner saves a file named CRASH_yyyyMMdd_HHmmss.txt, such as CRASH_20261017_143005.txt, in ~/Library/Application Support/Octopus Scanner.
  • It holds the exit code and the Octopus Server window's log. The newest five are kept.
  • The log shows Process crashed. Dump saved to followed by the file name.
  • Unexpected errors in the Mac app itself are added to crash.log in ~/Library/Application Support/Octopus Scanner/logs.
• Windows: There is no per-crash file for the engine. Errors in the Windows app itself are added to crash.log in %LocalAppData%\OctopusScanner\logs. For engine problems, export the logs with Preferences > Data > Export Activity Logs and attach that file.

Windows shows Windows protected your PC

CauseMicrosoft Defender SmartScreen warns about apps that aren't signed with a verified developer certificate.

FixCheck the file's hash, then follow the Windows steps in the Security Warnings Guide, How to get things running section.

macOS won't open the app, or says it is damaged

CauseGatekeeper blocks apps that aren't notarised by Apple.

FixCheck the file's hash, then follow the macOS steps in the Security Warnings Guide, How to get things running section, which include the Terminal command for the "damaged" message. Don't move the app to the Trash.

Application Integrity Error

CauseOctopus Scanner checks its interface file at startup. This error means the file is corrupt or has been changed.

FixReinstall Octopus Scanner, as described below for your system.

• macOS: Move Octopus Scanner from Applications to the Trash, then install it again. Your reports are kept in ~/Library/Application Support/Octopus Scanner.
• Windows: Reinstall Octopus Scanner. If the error continues, delete only the %LocalAppData%\OctopusScanner\app folder and open the app again. Don't delete the whole OctopusScanner folder, because your reports are in the reports folder inside it.

Don't edit index.html or any other internal file.

The scanner has not started

CauseThe engine stopped, couldn't claim its port or never answered. The startup screen then says The scanner has not started. The activity log has what the scanner reported.

FixRead the System Activity log in the Octopus Server window for the reason. If no free port was found, choose a different Server Port in Preferences > Options > Advanced. The new port applies the next time the scanner starts. To try again without quitting, select Restart Scanner when it is shown.

A busy port is handled for you in most cases. Before the engine starts, Octopus Scanner checks the Server Port, which is 3000 by default:

1. If an earlier Octopus engine is still using the port, it is closed, and the log shows Closing a previous Octopus engine still using port [port]...
2. If another app is using the port, Octopus Scanner tries up to 20 higher ports and uses the first free one. The log shows Port [port] is in use by another app, so Octopus is using port [new port] instead. The other port is used for this session only. Your Server Port setting doesn't change.
3. Only when none of those ports is free does the log show No free port found between [port] and [last port]. Trying [port] anyway. The engine then usually fails to start, and the startup screen says The server port is already in use.

The engine also stops if another program has the same port on this computer's IPv6 loopback address (::1), because that program could otherwise receive requests meant for the interface. The log shows Another program is already using port [port] on this computer's IPv6 address, so the interface could be intercepted. Exiting. Close the other program or choose a different Server Port.

The scanner has stopped

CauseThe engine stopped after it had started, for example because it crashed. On macOS, the startup screen says The scanner has stopped, and Scanner Stopped appears beside the System Activity heading. On Windows, the status shows Offline or Offline (Code N). The scanning interface then says the engine didn't respond. On Windows, Octopus Scanner first restarts the engine for you, up to 3 times in 10 minutes. After the third time it stops trying, and the Activity Log says to use Restart Scanner.

FixSelect Restart Scanner to start the engine again without quitting the app. On macOS it is in place of Open Interface, beside the System Activity heading and on the startup screen, and in File > Restart Scanner (Command+R). On Windows it is next to Open Interface and in the notification area icon's menu, and Alt+R selects it. Then refresh the scanning interface, or select Open Interface. If it stops again, read the Activity Log for the reason, export the logs and report a bug.

Offline (Code N)

CauseThe engine stopped with an error. The number is its exit code. A status of Offline with no code means the engine stopped normally.

FixRead the System Activity log in the Octopus Server window for the reason, then select Restart Scanner, or quit and reopen Octopus Scanner. If it keeps happening, export the logs and report a bug.

Crash loop — stopped (Windows)

CauseThe engine stopped with an error three times in under 60 seconds. The log shows Crash loop detected: Node exited 3 times in under 60 s. Check the logs, or reinstall if this keeps happening.

FixRead the Activity Log for the reason, then quit and reopen Octopus Scanner. If it happens again, reinstall Octopus Scanner as described in the Install Guide.

Google Chrome is installed but not found (Windows)

CauseOctopus Scanner looks for Chrome only in its standard install folders: %LocalAppData%, Program Files and Program Files (x86), each followed by \Google\Chrome\Application\chrome.exe. Chrome installed anywhere else, and Chrome Beta, Canary or portable copies, aren't found. The startup screen then says Octopus Scanner needs Google Chrome.

FixSelect Download Chrome and install the standard release of Chrome, then select Check Again. To open past reports without scanning, select Continue Without Scanning. On macOS, Chrome must be in Applications or in the Applications folder in your home folder.

Looks like you're offline

CauseOctopus Scanner couldn't reach the internet to check for app and rule updates at startup. The screen says Connect to get the latest updates. You can continue offline for now. It doesn't appear when Offline Mode is on in Preferences > Options > Advanced.

FixSelect Continue. You can scan as usual. To check for updates, reconnect and open Octopus Scanner again.

Couldn't check for the update (Windows)

CauseAfter you selected Download Update, the signed update information couldn't be downloaded or verified, for example because the connection dropped. Nothing was downloaded.

FixCheck your internet connection, then select Try Again. To keep using the version you have for now, select Continue.

Oops, Octopus feels confused

CauseComponent Update Notifications are off, and components haven't been updated. The screen appears once for each version, 180 days after it first opened, when no newer version was found. It explains that without component updates, Octopus Scanner can miss security, bug and compatibility fixes.

FixTurn on Take it into our own tentacles, which turns on Component Update Notifications, then select Continue. Updates are then offered as they become ready, which keeps the app current. See How Octopus Scanner stays up to date.

Permission Required (macOS)

CauseWhen Octopus Scanner is kept in Documents, Desktop, Downloads or iCloud Drive, macOS asks for your approval before the app can read its own files.

FixSelect Allow in the macOS prompt. To avoid the prompt, move Octopus Scanner into your Applications folder.

Pages fail with timeouts or blocking messages

CauseMany websites use bot protection services, such as Cloudflare, Akamai or Imperva, that block automated tools.

FixIf you have permission to scan the website, the most reliable fix is to let the scanner through bot protection. If the site's team can't add an exception, and you still have permission to scan, try these in order.

1. Leave Adaptive Networking on: When a website pushes back, the scanner slows the crawl and recovers speed once requests succeed again. It doesn't turn Stealth Mode on for you. If Stealth Mode is off, the scan progress suggests turning it on.
2. Leave Stealth Mode on, which is the default: The scanner then hides automation signals and presents itself as an ordinary copy of Chrome on your computer, with a matching browser identity and a realistic screen size. It also varies the pause between pages, tells the site which page linked to the next and visits the home page first so the site can set its cookies.
3. Increase Crawl Delay: Try 2000 ms or more.
4. Turn off Disable GPU Acceleration: Some protection checks look for graphics support, which Chrome doesn't have while Disable GPU Acceleration is on. Turning it off can make scans less stable, so turn it back on if pages start to crash or windows go blank.
5. Use a visible browser: Enter a Login URL, even if the website has no sign-in, such as the site's home page.
   • The scan then starts in a visible browser window, which is often blocked less. Once the page has loaded, select Confirm Login is Complete to continue.
   • A Login URL also turns Persistent Session on, so turn it off before you scan if you don't want to keep cookies and sign-ins between scans, and it turns off Parallel Processing and Periodic Browser Restarts.

The scanner already waits when a website asks it to, for up to 30 seconds. If a website asks for a longer wait, the page is tried again later in the scan, and listed as Rate limited only if it's still refused. A bot protection check gets up to 15 seconds to finish before the page is listed as skipped. If checks keep failing on a website, it stops waiting for them so the scan isn't slowed down.

If bot protection blocks a viewport while viewports are scanned in parallel, the scanner logs a warning and scans that viewport again on its own afterwards. You don't need to change anything.

Let the scanner through bot protection

When you have permission to scan a website, its team can let the scan through instead of the scanner having to look like a visitor.

1. Choose a header and a code: In Advanced Options, with Show All Settings on, enter an Allowlist Header Name, such as X-Octopus-Scan, and a long, random Allowlist Header Value that only you and the website's team know.
2. Ask the website's team to allow it: Send them the header name and value privately. In Cloudflare, they can create a WAF custom rule that matches requests where that header equals the value, with the action Skip, and choose which protections to skip. Akamai, Imperva and other firewalls have similar exceptions for a request header.
3. Scan as usual: The header is added to every request to the website you entered, and to nothing else.

The value isn't saved with your settings, so enter it again after you restart Octopus Scanner. Change it if it might have been shared more widely, because anyone who knows it can use the same exception.

Restarting browser... or Browser crashed on [URL]. Restarting...

CauseRestarting browser after 25 pages... and Restarting browser... are routine. Periodic Browser Restarts releases memory every 25 pages by default. Browser crashed on [URL]. Restarting... means Chrome crashed on that page.

FixNone is needed. After a crash, the scanner records it, restarts the browser and continues where it left off. If the same page crashes repeatedly, see Target closed or Session closed.

The interface stops updating during a scan

CauseThe interface lost its live connection to the engine, for example because the page was refreshed, the system froze or the network adapter went to sleep.

FixRefresh the page. The interface reconnects to the running scan automatically. No data is lost, because the scan continues in the engine whether or not the interface is connected.

Open the interface from the Octopus Scanner app.

CauseThe interface's address was typed or bookmarked into a browser, or an old interface window was reloaded after the engine restarted. For your security, the interface opens only from the app.

FixSelect Open Interface in the Octopus Server window, which opens the interface with a fresh, single-use link. On Windows, an interface window that is already open is replaced with a fresh one automatically when the engine restarts.

The interface window doesn't open (Windows)

CauseThe built-in window couldn't start, or the Microsoft Edge WebView2 Runtime is missing.

FixWhen the built-in window can't start, Octopus Scanner offers to open the interface in your web browser instead. If WebView2 is missing, it asks you to install or repair it, then open the window again.

Scans are slow or unstable on a smaller computer

CauseOn a computer with less than 16 GB of RAM or fewer than six processor cores, the Octopus Server window warns at startup that scans may be unstable. The Install Guide lists the full system requirements.

FixExpect slower scans. Scan pages one at a time rather than with Parallel Processing, and set Screenshot Mode to capture fewer screenshots or none. Parallel Processing concurrency is already capped automatically on computers with less memory.

The computer sleeps during a scan

CauseWhile a scan runs, Octopus Scanner stops the computer and display from sleeping when idle. Closing the lid, or choosing Sleep yourself, still suspends the computer and pauses the scan.

FixKeep the computer awake and plugged in during long scans.

Memory use is high

CauseParallel Processing, very long crawls and keeping every instance of every rule all increase memory use.

Fix

• Parallel Processing: High memory use is expected. Reduce Concurrency if the computer struggles.
• Periodic Browser Restarts: Leave it on. It restarts the browser every 25 pages by default to release memory.
• Show Every Instance Of Every Rule: Leave it off unless you need every instance in the report. It keeps memory use and report size predictable.

Execution context was destroyed

CauseThe page navigated or refreshed while it was being analysed, often because of a meta refresh redirect.

FixIncrease Crawl Page Timeout under Backend Fine-Tuning for crawls, or Navigation Timeout under Advanced Options for other scans.

Target closed or Session closed

CauseThe browser tab crashed, usually because a heavy page ran out of memory.

FixIf it happens again on the same page, make sure Disable GPU Acceleration is selected under Advanced Options. It is selected by default and is often more stable. If you turned it off to get past bot protection, turning it back on may stop the crashes.

Refused fetch: private/loopback IP literal

CauseWhen you scan a public website, the scanner refuses to contact private, local or loopback addresses, as a safety measure. Refused fetch messages, including Refused fetch: [host] resolves to private/loopback, mean the scanner didn't fetch a robots.txt file or sitemap at such an address. Requests that the page itself makes to these addresses are blocked too, and are logged as Blocked a request to a private network address.

FixNothing is broken. Scans that start on an internal, local or file:// address aren't restricted.

The sign-in or recording window is blank

CauseThe computer has no graphics acceleration available, which is common on virtual machines and remote desktop sessions, so Chrome can't draw a visible window properly.

FixLeave Disable GPU Acceleration selected, which is the default. Chrome then uses software rendering in the Login URL, journey recording and Interactive Mode windows, as well as during scans.

The window takes a while to appear (Windows)

CauseOn slower computers, the browser can take several seconds to appear after the scan says it is waiting for you.

FixWait for the window. The scan waits up to 20 hours for Confirm Login is Complete, so take as long as you need. If the sign-in window is closed, it continues without signing in and logs Manual login confirmation was not received (timed out or cancelled).

A scan won't start: Enter this sensitive value

CauseA user journey contains a step marked Sensitive Value, such as a password. Sensitive values are never saved with a configuration or a report, so you enter them again before each scan.

FixThe interface opens Customise Scan, shows the step and moves focus to the field, with the message Enter this sensitive value. It is not saved, so it is needed before each scan. Type the value and start the scan again. To stop a value being treated this way, clear Sensitive Value on that step. The value is then saved in plain text with the configuration.

User Journey Error: The journey doesn't scan any pages.

CauseThe recorder captures your interactions, and you decide where the audit runs. A journey without a Scan Page step is rejected before the scan starts.

FixAdd a Scan Page step at each point you want audited.

Persistent Session turns itself on

CauseEntering a Login URL turns Persistent Session on, so your sign-in can be reused throughout the scan.

FixTurn it off again if you want each scan to start signed out. It then stays off. To delete a stored session at any time, select Options > Clear Session in the footer of the scanning interface. Clear Session is shown when Show All Settings is on, and is disabled while a scan is running or a journey is recording.

A scan is already running in another window

CauseOctopus Scanner runs one scan at a time. If you start a scan while another is running, for example from a second interface window, the interface shows A scan is already running in another window. Showing its progress here. and follows the running scan instead.

FixWait for the running scan to finish, or select Cancel Scan, then start your scan again.

Shut Down After Scan does nothing (macOS)

CauseOn macOS, Shut Down After Scan asks System Events to shut the computer down. The first time, macOS asks whether Octopus Scanner may control System Events. If that permission is refused, the 60-second countdown finishes but the computer stays on, and the System Activity log in the Octopus Server window shows Your Mac did not shut down.

FixOpen System Settings > Privacy & Security > Automation, find Octopus Scanner and turn on System Events. See Preferences: Options for the setting itself.

Some options are unavailable for local files (file:///)

CauseWeb-only features don't apply to local files. Crawl and sitemap options, Login URL, Parallel Processing, journey recording, Stealth Mode and Respect robots.txt are turned off.

FixNone is needed. The file is audited on your computer, although anything it references on the web is still loaded.

Content inside embedded frames is missing or not tested

CauseWith Scan Iframes on, content inside frames is audited, including frames from other websites, and findings are reported with screenshots like any other issue. A frame that can't be reached is reported as not tested. If frames stop responding, the scanner falls back to the main page only and flags this in the report.

FixMake sure Scan Iframes is on, which is the default. For frames reported as not tested, check them manually.

Options are greyed out

CauseSome features can't be combined, or don't apply to the kind of scan you have set up, so choosing one turns others off or locks them. A greyed-out area shows a short note explaining why, and often what to change to use it.

FixRead the note beside the greyed-out setting. For the full list, find the setting in the table that conflicts with the option you need, and follow the last column.

In the table, the Scan Behaviour options are Attempt to Dismiss Overlays, Force-Reveal Hidden Content For Scanning, Scan Dark Mode, Enable Content Interaction (Deep Scan) and Crawl Site Even When Sitemap Provided. The Crawl Options are every setting in the Crawl Options section, including Enable Parallel Processing, Block Analytics Trackers, Advanced Link Discovery and Apply Smart Dedup & Coverage Caps.

Traffic isn't going through the proxy

CauseTraffic to the scanned website, including the scanner's own robots.txt and sitemap requests, goes through the Proxy Server URL you set. HTTP, HTTPS, SOCKS4 and SOCKS5 proxies are supported. A username and password in the proxy address are used for robots.txt and sitemap requests, and for the scanning browser on scans of public websites. On scans that start on your local network, the browser doesn't sign in to the proxy. With several proxies listed, pages rotate through them, while robots.txt and sitemap requests use the first. Local file scans never use a proxy.

FixCheck the username and password in the proxy address. For scans that start on your local network, use a proxy that doesn't ask for a sign-in.

robots.txt or sitemaps fail while a proxy is set

CauseThe proxy refused the connection, or rejected the credentials.

FixCheck the address, port and credentials. The Activity Log names the failure, for example that the proxy refused the connection. If only sitemap requests fail, page scanning continues. If robots.txt can't be reached, the whole site is treated as off-limits until you fix the proxy or turn off Respect robots.txt. If the proxy refuses every connection, page loads fail too and are reported as proxy errors.

Screenshots are in a folder instead of the report

CauseEmbedding every image would make the HTML file too large to open comfortably. The scanner saves screenshots to a separate _screenshots folder when there are more than 400, or when their combined size is more than 100 MB.

FixKeep the _screenshots folder beside the HTML file. The report refers to the images by relative path.

Screenshots stop part-way through a large scan

CauseTo save memory, the scanner stops taking new screenshots for the rest of the scan once it has found more than 150,000 issue instances. Issues found after that point appear in the report without screenshots. The only notice is the Activity Log message Issue limit reached. Disabling new screenshots to save resources.

FixNothing is broken, and every issue is still recorded. To get screenshots for the later pages, scan them separately, for example with Scan Specific URLs / Add Crawl Seeds, or split the website into smaller scans with Exclude URL Patterns.

Extra files appear beside the report

CauseEvery HTML scan also produces a companion CSV that contains every instance, untruncated. Whenever screenshots are captured, a screenshots ZIP is available too. It is saved beside the report when screenshots are embedded, and built when you download it when they are in a folder. If the finished HTML file is larger than 30 MB, the scanner adds a note that it may be slow to open.

FixNothing is wrong. For a very large report, use the CSV for data work and the ZIP for evidence. The Report Anatomy guide explains each file.

A CSV report was produced instead of HTML

CauseThis is rare. Reports are written to disk as the scan runs, so a CSV-only result means the scan was too large, or memory too short, for a safe HTML report. One of these safety guards stepped in:

• Too many issues: The scan found more than 150,000 issue instances and the results couldn't be assembled during the scan. The Activity Log shows Switching to CSV: issue count ([count]) is too large for a safe HTML report. The Octopus Server window shows Report size limit hit — CSV generated.
• Low memory after the scan: Before building the HTML report, the scanner checks how full its memory is.
  • Above 65%, or above 85% when results were assembled during the scan, it switches to CSV.
  • The Activity Log shows a message that starts Low RAM: Node heap is [percent]% full and ends Generating CSV instead — open the CSV in a spreadsheet or re-run on a machine with more RAM for a full HTML report.
  • The Octopus Server window shows Low RAM — CSV report generated.
• Results too large to hold: The results were too large to load back into memory. The Activity Log shows Data too large for HTML. Switching to CSV report. Reason: Result set too large for HTML generation (>1GB RAM limit).
• Memory guards during the scan: If memory runs short while the scan is running, the scanner first reduces detail, then stops assembling results for the HTML report.

If any guard trips, the scanner produces a streaming CSV instead, which can't run out of memory. Scan data isn't lost. The full wording of each message is in Activity Log messages.

FixIf it happens often, use a computer with more memory, or follow the advice under Memory use is high.

The report is very large or slow to open

CauseShow Every Instance Of Every Rule is on, or the scan captured a large number of screenshots.

FixLeave Show Every Instance Of Every Rule off. The first 1,000 instances of each issue are enough to describe and fix it, and the companion CSV always holds the rest.

Old reports have disappeared

CauseReports are never deleted automatically. They are removed only when you delete them, either individually under Past Reports or with Remove Reports, which deletes reports older than the period you choose, along with their screenshots. Remove Reports appears once at least one report is older than 7 days.

FixCheck the reports folder. To open it, select Preferences > Data > Application Data in the Octopus Server window. Its location is listed under Where files are kept.

Nothing to update with these settings or Nothing to update with this waiting period

CauseNewer versions exist, but on the Dependency Patching screen they are above your Update Level or haven't passed your Waiting Period. The Node Runtime screen has a Waiting Period only.

FixThe screen says which applies, and when a held-back version becomes available. Waiting is the safest choice. If you need the update sooner, raise the Update Level or choose a shorter Waiting Period. See Dependency Patching in the User Guide.

A patch was discarded

CausePackages are screened against a public malware database before download, every downloaded package is checked against its published hash and signature, and the scanner must still start afterwards. If any check fails, the whole update is discarded and nothing changes.

FixNothing is broken, and your current components are still in use. Try again later. If your antivirus or security software blocked the download, see Antivirus and component updates.

Updated components and Revert

Updated components are newer versions of the dependencies or Node.js runtime that Octopus Scanner runs on, installed between releases through Dependency Patching or Node Runtime. They keep the app current, and scans, reports and Report Bug work as usual while they are in use.

If something misbehaves after an update: Select Revert in Preferences > Options > Advanced, then restart. Revert returns to the components this version shipped with. Installing a new version of Octopus Scanner also replaces updated components with the ones it ships with, the next time it opens. If the problem continues, report it with Report Bug.