Troubleshooting & Failure Modes

Attestly is designed to be resilient, but failures can occur across scanning, generation, and drift detection. Here is what to expect and how to resolve common issues.

Scan Failures

When a scan fails, the repository will show an error state in the dashboard. Common causes include:

• Repository access revoked: Reconnect the GitHub integration.
• Unsupported language or empty repo: Ensure the repo contains valid source code or supported lockfiles.
• Timeouts: Scans exceeding the 5-minute limit (typically on very large monorepos) will fail. If this happens consistently, contact support.

Recovery: Click the "Trigger Scan" button on the repository page to retry.

Incorrect Findings (False Positives)

The scanner uses conservative heuristics, which can sometimes lead to false positives (e.g., flagging a test variable as a PII field).

Recovery:

1. Use the Custom Detectors feature (.attestly/detectors.ts) to explicitly disable the misfiring rule for your repo.
2. The next scan will clear the finding, and any affected documents will enter a drift state for review.

Drift Rejection

If the drift bot opens a PR check indicating document changes, but you reject the changes in the dashboard:

• The document remains published in its previous state.
• The PR check on GitHub will be marked as failed, blocking merge (if branch protection is enforced).
• The drift alert remains open in your Attestly dashboard until the underlying code is changed or the drift is approved.

Recovery: Either approve the drift to publish the new document version, or remove the code changes that triggered the drift.

Document Generation Failures

Document generation relies on external LLM APIs (OpenAI or BYO-LLM). If generation fails:

• A draft will not be produced, and an error will be logged in the audit trail.
• This does not affect currently published documents.

Recovery: Document generation automatically retries transient errors. If it fails permanently, check the audit log for specific API errors (e.g., rate limits on your BYO-LLM key) and manually trigger a regeneration from the document editor.