Help Center / Troubleshooting
Troubleshooting
Common situations and exactly how to resolve them. For exact wording of any message, see the message reference.
The app won't load / shows "Loading…" forever
- Make sure you're serving over HTTP, not opening the file with
file://. Run a static server (e.g.python3 -m http.server 8000) and open/app/. - The app fetches its data packs (questionnaires, clauses, controls, sample, scan-checks). If those 404, check the folder structure is intact.
- Open the browser console for errors; the cloud module failing to load is harmless (the app stays local-first).
Portal link is "expired" or "invalid"
| Symptom | Cause | Fix |
|---|---|---|
| Banner shows "link expired" | The 14-day token lifetime passed. | Click Send to vendor portal again to mint a fresh link; the vendor refills. |
| Banner shows "link signature mismatch…" | The link was altered, or it was signed by a different install. | Re-send from this install. Don't hand-edit the URL after the #. |
| Vendor sees "This questionnaire link can't be opened" | The link is expired or malformed. | Send a fresh link. |
| Import says the link "is no longer valid" | Token expired/tampered between send and import. | Re-send and have the vendor refill. |
See Vendor email portal for the full token model.
Scan was "deferred" or returned no results
| Symptom | Why | What to do |
|---|---|---|
| Summary lists TLS/headers/ports/breach as "Deferred to the hosted runner" | Those probes can't run from a browser; they're the hosted runner's job (deferred). | Expected. Live email-auth (SPF/DMARC) still runs. The deferred probes arrive with the hosted runner. |
| "Refusing to scan: …" | The domain failed the SSRF guard (IP literal, private range, reserved TLD like .example, port, credentials, or not a valid public domain). | Use a real public domain. The sample vendors use .example and are refused on purpose — run a simulated scan instead to explore. |
| "Add a primary domain for this vendor to scan it." | The vendor has no domain. | Add a Primary domain on the vendor. |
| Live scan ran but added 0 findings | Email auth looked fine, or those checks already had findings (merged by check id). | Nothing to fix — that's a clean email-auth posture. Try a simulated scan for the deferred categories. |
| "Live scan could not run: …" | The DNS-over-HTTPS lookup failed (network/DNS). | Check connectivity; retry. A failed lookup is never treated as "records absent." |
Attachment upload problems
| Message | Fix |
|---|---|
| "file type .xxx is not allowed" | Use pdf, png, jpg, jpeg, csv, xlsx, or docx. |
| "file exceeds 25 MB limit" | Compress/split the file under 25 MB. |
| "empty file" | The file is 0 bytes; re-export it. |
| "Choose a file to attach." | Pick a file before clicking Attach document. |
| Open shows "stub attachment's bytes were dropped on reload" | You're in local-stub mode and reloaded. Re-attach to view this session, or sign in to Cloud to store it in R2. |
| "Upload failed: R2 upload failed: HTTP …" | The signed-in R2 path errored (backend reachability). Retry; until the hosted storage is enabled, use the local-stub path. |
See Evidence attachments.
BAA expiry / review flags look wrong
- The review flag is driven by Next review date; the executed-document flag is driven by Term end. They're separate — set both.
- A PHI vendor with no BAA always shows "BAA required, none on file" (critical) and a −15 score factor until you set a BAA status and attach/record the agreement.
- "missing-doc" persists until you attach a file with kind
baa.
See BAA tracking.
A send wasn't delivered (offline)
If you're signed out, sends are simulated locally — nothing is emailed. The confirmation says so. Deliver the portal link yourself by copying the open portal ↗ URL, or sign in to the cloud tier for live delivery (deferred backend). See Notifications & offline.
My data disappeared
- Data is per-browser-profile in
localStorage. A different browser, device, profile, or a "clear browsing data" action will not show it. - Restore from a JSON export if you made one (Vendors tab → Export portfolio).
- To keep data across devices, sign in to the cloud tier.
Import did nothing / skipped rows
- "skipped N duplicate(s)" means rows matched an existing
primary_domain— dedupe is working as intended. - "missing required 'name' column" means your header row is wrong. Include a header row with at least
name. - Rows with no
nameare reported as errors and skipped.