Troubleshoot setup
| Symptom | Check | Next action |
|---|---|---|
| Invitation missing | Portal delivery state, expiry and junk folder | Resend to the intended recipient; older links are invalidated |
| MFA code rejected | Device clock and latest authenticator code | Wait for the next code; already-used codes cannot be reused |
| Agent has no recent contact | Endpoint, credential expiry/revocation, connectivity and process status | Restore connectivity or enroll a replacement credential |
| Configuration awaiting agent | Agent version, process and heartbeat | Upgrade to scanner 0.11.0+, opt in locally and restart |
| Configuration rejected | Reopen Configure agent for the fixed reason code | For local-opt-in-required, enable managedConfiguration locally; for outside-local-scope, narrow remote scope or obtain approval to change local limits; for invalid-configuration, check paths and types |
| Job rejected by local scope | Exact host:port, repository path and capabilities | Correct the intended job or approved local scope |
| Incomplete analysis | Read errors, Python syntax and manifest diagnostics | Fix inputs or use a compatible interpreter, then rerun |
| HTTP 429 | Retry-After response header | Wait and preserve the ingestion idempotency key |
| Access stops after suspension | Workspace status in the tenant portal | An administrator must resume the workspace |
Diagnose the local agent
Run python scanner/qr.py doctor --config agent.local.json in the agent environment. Fix failed check codes, then rerun. config.repositoryRoots.N identifies the zero-based list entry without disclosing its path. Install dependencies using that environment's python -m pip install -r scanner/requirements.txt. Do not solve read errors by granting blanket administrator permissions; grant the intended account access only to approved repositories.
Passing doctor does not prove connectivity or credential validity. If all checks pass but contact is missing, review the process, outbound HTTPS access, and credential expiry or revocation. The report is local-only and excludes configured values.
A useful support report
Include workspace name, agent/job identifiers, operating system, Python/scanner versions, timestamp, action attempted, and the redacted error category. Explain what you expected and what occurred. Exclude tokens, password-reset URLs, MFA setup keys, repository contents and packet payloads.
Understand the limits
Discovery coverage counts observations; it does not prove your entire environment was inspected. A hybrid key exchange does not imply post-quantum authentication. Manifest declarations do not prove runtime use. Review evidence and confidence before making migration decisions.