Troubleshooting
The first checks for every kind of issue — setup, runs, runners, automations, credentials, and compliance — written as flowcharts you can walk in order.
Most things that go wrong on NullSquare fall into one of a few categories: scope or target not ready, runner not online, credits or concurrency limits reached, missing context, or rules of engagement that exclude what you are trying to test. This page is the diagnostic checklist for each.
Walk the relevant section in order — they are arranged from "almost always the cause" to "rarely the cause" — and most issues resolve before you reach the bottom.
What you will learn
- First checks. The four-question sweep that resolves most issues.
- Run-specific issues. Why a run will not start, paused unexpectedly, or returned empty.
- Runner-specific issues. Offline, unreachable, or unauthorized for the work.
- When to contact support. What to share so support can help in one round.
First checks (try these before anything else)
When something is not working, these four questions resolve the majority of cases. Walk them in order before deeper diagnosis.
- Is the active scope correct? Many "missing" things are in a different scope.
- Are the targets verified (public) or authorized (internal)? Unverified targets are silently excluded.
- For internal work, is the attached runner online? Open Runners → the runner detail page.
- Do credits and concurrency allow a new run? Check Settings → Billing.
Run problems
If a run will not start, paused unexpectedly, or finished with less output than expected, work the list below.
- Run will not start — credits depleted, concurrency limit reached, scope has no verified target, or RoE excludes the entire target.
- Run paused with "approval" — Safe Mode is on for this scope. Open the run and approve, request feedback, or discard the plan.
- Run paused with "credits" — refill from Settings → Billing.
- Run paused with "runner" — attached private runner went offline. Bring it back online or attach a different one.
- Run completed but empty — RoE may be excluding too much, the target may be unreachable, or the goal may be off-scope. Check the run's plan tab for what the agent expected to do.
- Run failed — open the run detail page; the failure reason is shown at the top of Overview.
Runner problems
- Runner offline — confirm Docker is running on the host and the host has outbound network access.
- Runner registered but unreachable for targets — confirm the host can ping/connect to the target subnet. If a person on that host cannot reach the target, the agent cannot either.
- Runner not attached to the scope — open the scope and assign an online runner.
- Token rotated — redeploy with the updated install command from the runner detail page.
- Runner quarantined — the runner reported repeated errors. Review logs on the runner host, then reconnect.
Target and verification problems
- Target stuck "pending verification" — confirm the DNS TXT or HTTP file is reachable from the public internet, not just inside your network. DNS propagation can take a few minutes.
- Verification works but discovery returns nothing — the host may be behind WAF or geo-blocking. Add the agent's egress range to your allowlist if your environment supports it.
- Internal CIDR not assessed — make sure private-runner execution is selected on the run.
Automation problems
- Automation skipped firing — open the automation's history; the most common reason is an offline runner that did not recover within the grace window.
- Automation paused unexpectedly — credits dipped below the auto-pause threshold. Refill or adjust the threshold in Settings → Billing.
- Automation runs but produces nothing — same diagnosis as an empty manual run. Tune the goal and confirm the scope context is current.
Compliance and evidence problems
- A control stays "gap" after a run — agent-tested evidence applies only to controls the assessment scope covered. Add a goal that exercises that control, or upload manual evidence.
- Uploaded evidence does not pass a control — uploaded evidence needs review and approval before it counts. Open the evidence library, review, and approve.
- Integration evidence is stale — integrations sync on a cadence; trigger a manual sync from the integration page if you need it fresh.
When to contact support
If first checks did not resolve the issue, contact support with the following so we can help in a single round: the organization name, the scope name, the run ID (or automation ID), the time the issue occurred, and a description of what you expected vs. what happened.