Reference

Troubleshooting

Error codes and workflow states you may see in PWR Studio, what each one means and what to do about it.

Errors from PWR carry a human-readable message and a machine-readable code:

{ "detail": "human readable message", "code": "machine_code" }

This page lists the codes and states you are most likely to meet. Where a run was refused, the code also appears on the run under Executions as an execution.refused event.

A queued task never starts

Likely cause	What to check
The plan's concurrent-run limit or the agent's own concurrency limit is reached	Wait for running work to finish, or raise the agent's limit
A daily organization quota is reached	Look for an `execution.quota_exceeded` event on the run
The task has a tool call with an unknown outcome	The task shows as blocked; see "Needs reconciliation" below
Dependencies are not completed	The task moved to `blocked` instead of `queued`

A run was refused

Code	Meaning	What to do
`provider_not_executable`	The agent's provider cannot run work yet	Choose an executable provider. See PWR Auto
`credential_unavailable`	The agent's key is revoked, for another provider, or cannot be read	Rotate or rebind the credential. BYOK never falls back to a managed key
`managed_model_unavailable`	The agent has no key and no managed account exists for that provider	Bind a credential or pick another provider
`model_not_active`	The model is deprecated or disabled	Pick an active model or use PWR Auto
`model_not_available_byok`	The model is not offered for your own key	Pick another model
`provider_not_approved`	Your model policy does not approve that provider	An owner updates the policy
`no_eligible_model`	PWR Auto found no model that passes the filters	The message lists each exclusion: context size, cost cap, capabilities
`provider_unavailable`	The provider refused recently and no fallback is allowed or reachable	Wait for the 15-minute cooldown, or allow fallback
`workspace_missing`	The project has no usable workspace source	Connect a repository
`subscription_inactive`	No active subscription	An owner subscribes or fixes the payment
`insufficient_credits`	Balance is empty or below the run's estimate or cap	Top up, or lower the cost cap
`budget_exhausted`	The monthly hard limit is reached	An owner raises the budget
`concurrency_limit`	The plan's concurrent-run limit is reached	Wait or change plan

Refused runs are not retried automatically.

Task and board errors

Code	Meaning
`illegal_transition`	The task cannot make that move from its current status, or a guard refused it. For example, queueing with an agent whose provider is not executable
`illegal_move`	No legal path exists from the card's column to the target column. The response lists allowed targets
`task_active`	Queued or running tasks cannot be edited
`task_terminal`	Completed or cancelled tasks cannot be edited
`version_conflict`	Someone else changed the task. Reload and retry
`dependency_error`	The dependency is in another project, cancelled, or would create a cycle
`retry`	Transient contention. Send the request again
`task_in_sprint`	The task is already in another open sprint
`acceptance_criteria_required`	Sprint execution needs acceptance criteria on every selected task
`agent_required`, `budget_required`	Sprint execution needs an agent and a budget

Workflow states

State	Cause	What to do
`validation_failed`	Your validation command failed. With validation required, nothing was pushed	Fix the cause and retry the task, or re-run validation
`push_failed`	Commit or push error, an unreachable remote, a detected secret, or a scope violation on a tests-only task	Read the last error. Remove the secret or out-of-scope change and retry
`review_blocked`	The reviewer returned `block`, failed, or produced a verdict that could not be parsed	Request a review again after changes
`ci_pending`	Required checks have not reported, or no webhook arrived	Refresh CI from the review page
`merge_failed`	GitHub refused the merge	Read the reason and merge again once fixed
`needs_reconciliation`	A push, pull request creation, merge or tool call has an unknown outcome	See below

A task whose agent changed nothing ends in awaiting_approval with the message "the agent produced no changes to push". No branch or pull request is created.

Needs reconciliation

PWR records every external write before sending it. If the result is unknown, for example GitHub answered with a server error or the connection dropped after sending, PWR does not retry blindly. An admin opens Settings → Operations, checks on GitHub or in the integration what actually happened, and resolves the operation as succeeded or failed. PWR then applies the consequence, such as adopting the existing pull request or marking the merge complete.

Approval and merge errors

Code	Meaning
`head_mismatch`	New commits arrived. Reload and review the current commit
`merge_in_progress`	Another merge of this pull request started less than a minute ago
`workflow_conflict`	The pull request is closed, or there is none
`review_pending`	A review is already running
`no_review_agent`	No reviewer agent is available for the task

The merge is blocked

A blocked merge lists which of the 11 gate checks failed. Common cases:

ci fails with no checks. With ci_mode set to required, the gate stays blocked until the repository defines required checks. Add required checks, or set ci_mode to if_configured in the project's workflow policy.
branch_protection fails. Your branch protection requires approving reviews on GitHub. PWR approvals cannot satisfy that rule.
human_approval or independent_review fails after a push. New commits invalidated them. Review and approve the current commit.
repository_authorized fails. The GitHub App was uninstalled or suspended, or the repository was removed from it.
no_uncertain_operations fails. Reconcile the open operation first.

GitHub connection errors

Code	Meaning
`invalid_state`, `state_consumed`, `state_expired`	The install link was for another user or organization, already used, or older than 15 minutes. Start again from PWR Studio
`installation_not_owned`	You do not control that GitHub account. A personal account must be yours; for an organization you must be an active admin
`installation_claimed`	Another PWR organization already holds that installation
`installation_stale`	The installation predates your install link. Start again
`connection_unavailable`	The installation is revoked or suspended
`github_unavailable`	GitHub is not configured correctly on the PWR side. Contact us

Jira and issue tracker errors

Code or status	Meaning
`pm_credentials_expired` / `credentials_expired`	The token was refused. Rotate it on the connection
`permission_denied`	The account lacks a permission, or the GitHub App lacks the Issues permission
`connector_unavailable`	Linear and Notion cannot be connected yet
Conflict on an issue	The issue and its task both changed. Resolve by keeping local or external

Other codes

Code	Meaning
`rate_limited`	Too many sign-in attempts or too many open live streams
`last_owner`	An organization must keep at least one owner
`plan_limit_projects`, `plan_limit_members`, `plan_feature_disabled`	A plan limit applies. See Billing and credits
`template_unavailable`, `template_inputs_invalid`	See Workflow templates
`source_unavailable`	Coverage Autopilot needs a workspace source
`artifact_restricted`	That artifact's content is limited to developers and above
`tool_not_approved`	An admin must approve the integration tool first
`billing_disabled`	Billing is not enabled on this deployment

If you are stuck, contact us with the request id from the error.