Troubleshoot agents and workflows
Start with the exact status, stalled reason, or CLI error. Apply the fix directly below it, then retry only the failed action.
Setup
Agent setup cannot find Codex
Update Desktop or the One Horizon CLI and retry. Codex is bundled with the active runtime; a separate codex command on PATH is not required unless you configured that command explicitly.
Claude Code or Cursor is unavailable
Install the required CLI, place it on PATH, and authenticate it in the same environment that starts the agent. Claude Code needs claude; Cursor needs agent or cursor-agent. The desktop app or editor integration alone does not prove CLI authentication.
Keep provider tokens in the provider CLI or operating-system secret store. Do not paste credentials into workflow instructions, task text, comments, or documents.
Repository folder is rejected
Choose a writable folder inside a Git repository with a usable base branch. The repository folder is fixed for that agent on that machine; create another agent to point at a different repository.
The wizard stops at Skills
The Skills step is disabled. Continue setup without adding skills.
Publishing
Workflow will not publish
Open every highlighted step and fix the validation error. Confirm there is a start step, every route reaches an existing step or terminal outcome, feedback returns to an earlier step, review steps have approve, feedback, and reject routes, human gates have reviewers, and agent-to-agent routes have a target.
A published workflow returned to draft
Definition edits create unpublished changes. Publish again after validation. Removing a targeted agent or the last agent in a targeted group can also return affected definitions to draft and cancel active runs.
Launch
Workflow is missing from Send to…
Confirm the workflow is published and its Start from setting includes the current work type. Published workflows appear only for matching initiatives, bugs, or todos.
Launch is blocked
The work item may already have a running, waiting-for-review, or stalled workflow. Finish, cancel, or resolve that run before starting another workflow.
Launch failed after selection
Check that the first step still has an eligible online agent and that the definition remains valid. A failed launch does not create a run; fix the cause and launch again.
Connectivity
Local agent does not pick up work
Confirm the session targets the expected agent, the owner is signed in to the correct workspace, and the agent is online. Run one agent doctor, then inspect one agent status for local execution capacity, backpressure, and resource pressure.
Agent is stale or offline
Restart it from Desktop or with one agent stop followed by one agent start. If the process still drops, inspect one agent logs, the workflow file, provider authentication, and machine resource limits.
Execution
Session is queued but not running
Queued work still needs an eligible agent and an active claim. Check the target agent, execution mode, local owner, and whether another agent already holds the claim.
Session is stale
Bring the previous agent online so it can reclaim its stale session, or choose Try again to create a replacement run. Inspect the previous activity before retrying to avoid repeating an external side effect.
Activity says work is complete or a review says approved, then the session stalls
Final progress text does not complete a session. A reported review verdict can route the workflow, but the session still needs a terminal state. Inspect the terminal session state and activity, then restart the local agent before choosing Try again. Check any commit, push, comment, or external action first: the replacement session can repeat it.
Workflow hit a pass limit
Open the run and inspect the exhausted step and configured route. Resume skips that step and follows its route; change the definition for future runs when the loop itself is wrong.
Review
Review agent completed without routing
The review agent must report exactly one verdict: approve, feedback, or reject. Plain final text cannot route the workflow. If a verdict was reported but the session later errors, inspect the session before retrying the review step.
Review loop keeps returning to the same step
Inspect the feedback route, pass limit, and review document. Fix unresolved findings in the returned step instead of rerunning unchanged work.
Human review is waiting on the wrong person
Reassign the gate when the workflow allows it. Reassignment changes ownership without advancing the run or losing its review history.
Git and worktrees
Workspace preparation says the folder is not a Git repository
Choose the repository root or a folder inside it, then rerun one agent doctor. Confirm the configured base branch exists.
Worktree cleanup stopped because of local changes
Inspect both the task worktree and repository root. Commit, stash, or move changes you want to keep, then run one agent worktrees remove <task-or-path> again.
Forced worktree removal discards uncommitted changes. Preserve the branch and any required files before adding --force.
Cross-agent handoff says the branch was not pushed
Confirm the current step committed its changes and the runtime can push the shared workflow branch to origin. Do not bypass the handoff until the next agent can fetch the exact branch state.
Recreating or force-updating the workflow branch can lose the state another step expects. Preserve the current commit and remote branch before recovery.
Pull request or merge request handoff
The branch pushed but no PR or MR appeared
Confirm the matching GitHub or GitLab integration is connected to the workspace and the workflow has PR/MR creation enabled. Open a review manually from the pushed branch or retry creation; the agent does not need provider CLI credentials to create the review through One Horizon.
The linked work did not move to In Review
Check whether the run completed successfully and whether PR/MR creation returned an error. The status transition happens after One Horizon creates the review, not merely after a local commit.