Troubleshooting

First Things to Check

When something goes wrong, start here:

Is the workspace configured correctly? — GET /workspaces/{id} and verify source_repo_url, source_branch, source_root, execution_target
Are credentials valid? — POST /credential-configs/{id}/verify to test
Is the state backend reachable? — Check state_backend_config_id is set and the bucket exists
Is the run stuck or failed? — GET /workspaces/{workspaceId}/runs/{runId} to check status and error_summary

Symptoms: Run transitions to failed within seconds, no plan output.

Likely Cause	How to Verify	How to Fix
Wrong repo URL or branch	Check workspace `source_repo_url` and `source_branch`	`PATCH /workspaces/{id}` with correct values
Source root doesn’t exist	Check `source_root` matches directory in repo	Update `source_root` to correct path
Invalid credentials	`POST /credential-configs/{id}/verify` returns `valid: false`	Update or re-create credentials
State backend unreachable	Check `state_backend_config_id` and bucket permissions	Verify bucket exists and credentials have access
Wrong tool type	Check `effective_tool_type` on workspace	Set correct `tool_type` via `PATCH`

Symptoms: Run starts but fails during terraform plan or tofu plan.

Likely Cause	How to Verify	How to Fix
Terraform syntax error	Check logs for parse errors	Fix code in repo and re-run
Provider auth failure	Logs show provider-specific auth error	Check credential config for that provider
State lock conflict	Logs show “state lock held by…”	Force unlock if no other process is writing
Out of memory	Runner killed by OOM	Reduce plan scope or use agent mode with more resources

Symptoms: Run status stays queued for an extended period.

Likely Cause	How to Verify	How to Fix
Managed environment provisioning delay	Wait 1-2 minutes	Normal for first run in an org
Org job limit reached	Check if other runs are in progress for same org	Wait for other runs to complete (default: 3 per org)
Agent not running (agent mode)	Workspace `execution_target` is `agent`	Start your Forgecroft Agent and verify it’s polling
Billing inactive	`GET /billing` shows inactive subscription	Complete checkout or contact support

Symptoms: Run status is in_progress for longer than expected.

Likely Cause	How to Verify	How to Fix
Long-running plan (large state)	Check logs for progress	Wait — large plans can take many minutes
Runner crashed or lost connection	No new log lines for several minutes	Abort the run and re-run
Network timeout to state backend	Logs show timeout errors	Check state backend connectivity

POST /workspaces/{workspaceId}/runs/{runId}/abort

Works for runs in queued, in_progress, pending_policy, or pending_approval status. Returns 409 if already terminal.

Symptoms: Pushing to GitHub doesn’t create a run.

Likely Cause	How to Verify	How to Fix
No VCS integration configured	`GET /vcs-integrations` returns empty	Create a VCS integration or install GitHub App
Webhook not installed	Check GitHub repo settings → Webhooks	Re-install GitHub App or manually add webhook
Path filtering excludes changes	Changed files don’t match workspace `source_root`	Check `source_root` and `extra_checkout_paths`
Branch doesn’t match	Push is to a branch that doesn’t match `source_branch` or `pr_base_branch`	Update workspace branch config
Invalid webhook signature	Forgecroft returns 400 to GitHub	Check VCS integration secret/token

Symptoms: Run is pending_approval but no notification was received.

Likely Cause	How to Verify	How to Fix
No notification channel configured	Check workspace `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 OAuth flow
Email not configured	No Resend API key on server side	Use Slack or check server config

POST /workspaces/{workspaceId}/runs/{runId}/renotify

Re-sends approval notifications. Rate-limited to once per 5 minutes.

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 workspace-scoped but you’re accessing a different workspace	Create an org- or project-scoped key
Missing capability scope	Key has scoped capabilities but lacks the needed one	Create a new key with required capabilities
Wrong auth header	Using cookie instead of Bearer token	Use `Authorization: Bearer fc_live_...`