Failures and retry
Maestro distinguishes a provider being unavailable from a Goal failing. Both preserve the task worktree and evidence, but the recovery action is different.
Provider wait
Section titled “Provider wait”waiting_provider means no suitable provider lease is available because of quota, authentication,
offline state, cooldown or capacity. The runtime keeps the Goal checkpoint and can retry after the
provider becomes healthy. A provider that does not expose quota may show an unknown reading; that is
not proof that its authentication expired.
Resume versus retry
Section titled “Resume versus retry”- Resume reopens a
blocked,failedorwaiting_providerGoal in place after the user fixes the underlying problem. It keeps the same run, phase, step count and checkpoint. - Retry task is intentionally narrower: it accepts a Goal blocked by the budget circuit breaker, raises its maximum step ceiling and resumes the preserved worktree.
Use the task detail action or the corresponding Dashboard API. Do not create a new task just to work around a recoverable provider failure; doing so loses the original execution context.
Common causes
Section titled “Common causes”provider_not_foundorauth_required: install/login to the provider, then rescan.permission_denied: review the provider’s own permission policy; do not repeatedly retry unchanged.command_not_found: confirm the CLI is on the same PATH seen by the Maestro process.- validation failure: inspect the deterministic check artifact and prepare the project’s dependencies.
- no progress/repeated failure: split the request into smaller tasks or provide a corrective note.
The Troubleshooting page maps these symptoms to commands and logs.