Troubleshooting

Common problems and how to diagnose them. If a problem is not listed here, check the API response body for an error field with a specific error type and message.

Scan is stuck in pending

Symptom: GET /api/scan/{id} returns "status": "pending" for more than 5 minutes.

Causes and fixes:

• The async Lambda invocation failed silently. This can happen during periods of Lambda cold-start pressure. Submit the scan again.
• The repository is very large. Deep scans of large repositories with many files may take close to the 270-second budget. Polling for up to 10 minutes before declaring a timeout is reasonable.
• The repository URL was accepted but is not accessible. A private repository will be accepted by the API (URL validation only checks format) but will fail during the clone step. The status will update to failed. Verify the repository is public.

Scan status is failed

Symptom: GET /api/scan/{id} returns "status": "failed".

Causes and fixes:

• The repository is private. ticketyboo only scans public repositories. Make the repository public or use a fork.
• The repository URL is malformed. Ensure it is in the format https://github.com/owner/repo with no trailing slash or path.
• The repository was deleted or renamed between submission and scan execution. Verify the URL is still valid.
• The GitHub API rate limit was hit during dependency vulnerability lookup. Resubmit after a few minutes.

Gatekeep verdict is not_evaluated

Symptom: The scan completes but gatekeep.verdict is not_evaluated.

Causes and fixes:

• No devcontract.json file exists in the repository root. Check the file is present at the exact path devcontract.json (case-sensitive) at the root, not in a subdirectory.
• The file was added after the scan was submitted. The scan clones the repository at submission time. Ensure the commit with devcontract.json is pushed before submitting the scan.

Gatekeep verdict is error

Symptom: The scan completes but gatekeep.verdict is error.

Causes and fixes:

• The devcontract.json file contains invalid JSON. Validate it with a JSON linter.
• A gate has an unrecognised category value. Valid values: governance, dependency, code_quality, security, iac, secret, sast, license, quality.
• A gate has an unrecognised severity value. Valid values: critical, high, medium, low, info.
• A required field is missing. The gates array is required at the top level; each gate requires category, severity, and threshold.

Rate limit error (HTTP 429) on scan submission

Symptom: POST /api/scan returns HTTP 429 with error type rate_limited.

Causes and fixes:

• Shallow scan: 1 scan per IP per 24-hour window exceeded. Wait for the window to reset or submit from a different IP.
• Deep scan: 3 deep scans per IP per 7-day rolling window exceeded. Check remaining quota with GET /api/scan/deep-quota. Wait for the oldest scan in the window to expire, or switch to shallow scan.
• In CI environments (GitHub Actions, etc.) the runner IP is shared. Multiple repositories running concurrent scans from the same runner pool will share the rate limit. Stagger scan jobs or limit deep scans to pushes to main.

HTTP 402 on scan submission

Symptom: POST /api/scan returns HTTP 402.

Cause: The authenticated account has zero credits remaining.

Fix: Purchase a credit pack top-up via POST /api/topup or upgrade to a subscription plan. Check current balance with GET /api/account/me. Anonymous (unauthenticated) shallow scan submissions do not use credits but are subject to IP rate limits.

Brief Wizard shows no archetypes / API key error

Symptom: The VS Code Brief Wizard shows an error when opening, or the archetype list is empty.

Causes and fixes:

• The ticketyboo.apiKey setting is empty. Open VS Code Settings, search for ticketyboo, and enter your API key.
• The API key is invalid or has been rotated. Generate a new key from your account page.
• The ticketyboo.apiBase setting has been changed from the default. Reset it to https://api.ticketyboo.dev unless you are intentionally pointing at a different environment.

Deep scan layer missing from results

Symptom: Deep scan completes but findings from one or more layers (e.g. no secret or sast findings at all) are absent.

Causes and fixes:

• The layer timed out (45-second per-layer budget). Large repositories with many Python files may exhaust the SAST or quality layer budget. Partial results are still returned; the layer is skipped after timeout. This is expected behaviour.
• No files in the repository matched the layer's file selectors. For example, the SAST layer will produce no findings on a repository with only JSON or YAML files.
• All files in the relevant category exceed the size limit (500 KB per file for SAST). The scanner will record info-severity findings for oversized files.

CI workflow exits non-zero unexpectedly

Symptom: The GitHub Actions workflow fails on the Gatekeep check step despite no code changes.

Causes and fixes:

• A new CVE was published for a dependency that was previously safe. The dependency layer queries GHSA on each scan; the advisory database changes over time. Check the dependency findings for new CVEs.
• The contract threshold was already at zero and a pre-existing finding was not suppressed. Findings persist until the code is changed. Review whether the threshold should be increased temporarily while the finding is remediated.
• The contract was changed and the new threshold is lower than the current finding count. Review recent changes to devcontract.json.

Next steps

• Contracts FAQ
• Scan API reference
• Evidence JSON structure