Troubleshooting

AI agents: read the complete documentation index. Append .md to any docs URL for its Markdown version.

Start with the exact message in Chief and the task log. Relay connectivity, agent authentication, dependencies and usage limits are separate checks. Fix the reported cause before retrying work.

Relay offline

Symptom: Chief shows an offline relay or cannot dispatch work.

1. On the paired computer, open a terminal and run:

chief-relay

2. Keep the terminal open and the computer awake. Check its network connection.
3. Open Tutorial to check the paired device and last-seen information. Confirm this is the computer holding the project's folder and signed-in agents.
4. If authorization is required, open the printed verification URL, compare the code and select Approve Device. If the code expired, restart the relay to begin a new authorization flow.

Expected result: the sidebar shows Relay Connected. Then check agent readiness and the task's status before retrying. An online relay does not establish that an agent is signed in.

If chief-relay is not found, on macOS or Linux run:

export PATH="$HOME/.local/bin:$PATH"
chief-relay

On Windows, open a new PowerShell window after installation and try chief-relay again. For installation errors, read the terminal output and follow the quickstart.

Expired agent credentials

Symptom: the agent reports an authentication failure or Tutorial explicitly says sign-in is required.

1. On the relay computer, sign in again with that CLI agent. The agent guide lists each local sign-in flow.
2. For API-key providers, repair the local credential configuration and verify the provider account has access and balance. Do not paste keys into chat or support messages.
3. Check readiness in Tutorial. Restart the relay if a new installation or environment change has not been discovered.
4. Once ready, retry the affected failed task or select the ready planning provider as needed.

Expected result: Chief reports a ready provider and the next run no longer returns the authentication error. Switching providers is an option after preparing the new provider, rather than a repair for the original credentials.

Health check timed out or status unknown

A timeout or unknown health result does not by itself mean credentials expired. Retry the check and read its remediation message. Check the local agent and network if it persists. Reauthenticate when there is an actual authentication failure; follow switching agents if you decide to use another ready provider.

DeepSeek Harness's local health check does not validate the API key or balance. Diagnose an execution-time rejection using the task's error even if its local setup check passed.

Failed tasks

Symptom: a task is Failed, with controls to retry, revise or abandon.

1. Expand the card, read its result and open View log when available. Compare the failure with the definition of done.
2. Fix the specific cause: relay access, authentication, a missing local dependency, a provider limit or unclear scope.
3. Use Retry for another run attempt after fixing the environment. Use Revise when the objective, instructions or completion criteria need changing.
4. Use Abandon if you intend to archive the failed work instead. An archived failed task is read-only.

Expected result: the fresh attempt progresses and produces a new result. Review it before declaring the underlying problem solved. If it fails again, preserve the new error and ask Chief about that specific failure rather than retrying unchanged.

Blocked or queued tasks

Symptom: a task says Blocked, Waiting on, or remains queued.

• Open the dependency list and let prerequisite milestones finish. Queue approves dependent work but does not bypass prerequisites.
• Check You for an open manager task. Resolve or dismiss it deliberately to clear that prerequisite.
• For a blocked task with no blocked milestone dependency, use Re-dispatch when offered after addressing the stated blocker.
• If Chief offers Mark blocker done, use it only after verifying that prerequisite is complete. Remove dependency changes the plan: use it only if that prerequisite is no longer necessary.

Expected result: the waiting reason clears when all prerequisites are satisfied. If the status still blocks work, read the remaining reason and discuss it in project chat. Check relay and provider readiness before re-dispatching.

Auto mode stopped approving work

Read the auto-mode banner. A task or budget limit can pause the run; Resume lets you review and raise or remove limits, restarting its counts. A Held by auto mode badge needs your review of its reason and the task proposal. Check manager tasks as well. Disabled usage-cap fields mean the provider cannot enforce those caps, rather than that usage is free.

The Agents selector is locked during active or paused auto mode. Disable auto mode before changing the default worker and starting a new run.

A scheduled run did not happen

Read Chief's schedule confirmation for the time zone and next occurrence, then check chat notices and task history. The relay must be connected when work is due. Runs can be skipped after their lateness window, while a prior occurrence is active, or because of plan limits. Repeated failures can pause a schedule; changing its time leaves it paused. See Schedules and contact Support if a paused schedule needs attention.

Usage limit reached

Follow the reset or limit guidance in Chief. Chief plan limits, auto-mode caps and the provider account's quota are separate. Check Pricing for Chief limits and the agent provider for its own usage. Retry once capacity is available, or choose another ready provider where appropriate. Auto-mode limits do not override provider quotas.

Project path cannot be checked

Use an absolute path on the relay computer. Check its filesystem permissions, bring the relay online, and select Retry path check in the project form. A path from your phone or another computer cannot locate the relay's project. Return to project creation after the check succeeds.

Connected app cannot see a project

Check that you signed in to the right Chief account, selected the project during connection consent, and still have project access. The owner must enable Allow connected apps in project settings. A revoked connection needs a new sign-in. Use Settings → Connected apps for MCP grants; check the channel's project and linked Chief account for Discord.

Expected result: the assistant's list_projects includes the shared project, or Discord's status response identifies the connected project. See MCP setup or Discord for the appropriate connection flow.

Contact support with useful context

Visit Support and include the affected task or project, approximate failure time, operating system, selected provider, relay status, exact error and steps already tried. Include relevant redacted log lines. Keep API keys, tokens, pairing codes and unrelated private data out of the report.