Troubleshooting

First Things to Check

When something goes wrong, start here:

1. Is the gate authenticated? — FORGECROFT_API_KEY must be set to a valid key. Confirm the key in the Forgecroft console under Settings → API keys.
2. Is the repository connected? — Confirm the GitHub App is installed on the repository.
3. Has the repository’s evidence been ingested? — Without a system map, there is nothing to evaluate a change against. Ingest evidence through the Forgecroft console or the ontologize tool over MCP (Model Context Protocol).
4. Is your subscription active? — GET /billing shows the subscription status.

The Gate Returns insufficient_context

Symptoms: forgecroft-gate or the CI gate returns insufficient_context for a change.

Likely Cause	How to Verify	How to Fix
The repository has not been ingested	The map has no Components for the touched paths	Ingest evidence through the Forgecroft console or the ontologize tool over MCP (Model Context Protocol) to build the map
The change touches paths outside the mapped surface	The blast radius reports thin coverage for the touched area	Ingest the missing layer, or treat the verdict as advisory until coverage grows
No Controls scope the touched Components	GET /describe shows no Controls for the area	This is expected — the gate reports honestly rather than faking certainty

The CI Gate Doesn’t Post a Verdict

Symptoms: A pull request opens but no gate comment appears.

Likely Cause	How to Verify	How to Fix
The gate workflow isn’t installed	No forgecroft-gate job in the PR checks	Add the Forgecroft Gate GitHub Action workflow — see CI Gate
The API key in CI is missing or invalid	The workflow logs show a 401	Set FORGECROFT_API_KEY in the CI secrets
The GitHub App lacks comment permission	The app isn’t installed, or was removed	Re-install the GitHub App

Evidence Ingest Produces an Empty or Thin Map

Symptoms: Evidence ingest runs but few or no Components appear.

Likely Cause	How to Verify	How to Fix
Ingest ran against the wrong repository	The map has no Components for the repository you expected	Re-run ingest against the repository root
Proposals awaiting review	Proposals were created but not yet approved	Approve the pending proposals in the Forgecroft console

API Key Not Working

Symptoms: 401 or 403 responses when using an API key.

Likely Cause	How to Verify	How to Fix
Key is suspended	GET /api-keys/{id} shows suspended: true	PATCH /api-keys/{id} with {"suspended": false}
Key has expired	GET /api-keys/{id} shows past expires_at	Create a new key
Key scope doesn’t match resource	Key is project-scoped but you’re accessing a different project	Create an org- or project-scoped key
Missing capability scope	Key has scoped capabilities but lacks the needed one	Create a new key with the required capabilities
Wrong auth header	Using a cookie instead of a Bearer token	Use Authorization: Bearer fc_live_...

Notifications Not Received

Symptoms: An event occurs but no notification arrives.

Likely Cause	How to Verify	How to Fix
No notification config attached	Check the project’s notification_config_ids	Add a notification config
User notification preference is none	GET /me/notification-preferences	PUT /me/notification-preferences with email or slack_dm
Slack not connected	GET /slack-connections returns empty	Connect Slack via the OAuth flow

Related Guides

• CLI Reference — Commands and flags
• CI Gate — Wiring the gate into your pipeline
• API Keys — Creating and scoping keys
• GitHub App — Connecting repositories