Troubleshoot Workflows & Agents

Workflow and agent problems usually trace to an invalid definition, no eligible agent, an offline local runtime, or an unpublished branch during handoff.

Workflow will not publish

Publish validates the whole workflow definition. Fix highlighted steps before trying again.

Common causes:

• The workflow has no steps.
• A route points to a missing step.
• A human review step has no reviewer assignment.
• A review step is missing approve, feedback, or reject routes.
• A feedback route points forward instead of back to an earlier step.
• An agent-to-agent handoff has no target agent or group on the next agent step.
• A code-producing step targets an agent without the required capability.

Workflow launch is disabled

A work item can have only one active workflow run at a time. If the item already has a run in Running, Waiting for review, or Stalled, wait for that run to finish, cancel it, or resolve the active gate before launching another workflow.

Published workflows also appear only for matching work item types. Check the workflow Start from setting when a workflow is missing from Send to....

Local agent does not pick up work

Confirm the agent is online on the machine that owns it. Local agents are private to the signed-in owner, so other workspace members cannot trigger execution on your machine.

Run one agent doctor to check authentication, workspace selection, server agent registration, local runtime settings, the workflow file, the worktree root, and the agent binary.

If the agent was created on another machine, configure it locally before expecting it to claim sessions here. The chosen repository folder is stored on the machine that created the agent and is not synced to the server.

Session is stale or stuck

A session can become stale when the agent stops heartbeating. When the same agent polls again, it can reclaim stale sessions it last owned.

If the session is queued but not claimed, check targeting. A session pinned to one agent cannot be claimed by another agent. A group-targeted session can only be claimed by agents in that group.

Cross-agent handoff stalled

The workflow branch is shared handoff state. When a handoff crosses agent or group targets, the parent session must confirm the branch was pushed before the delegated session can continue.

If the run stalls with a missing branch handoff, inspect the parent session and push failure first. The next agent should not continue from an unpublished branch.

Review loop keeps returning to the same step

Each workflow step can be entered three times in one run. A fourth attempt stalls the run with a review feedback loop configuration reason.

Point Reject to Failed when rejection should stop the run. Use Feedback only when a prior step should revise and continue.