Troubleshooting

Start with pablo system:doctor, then look at the logs. Below are the problems people actually run into, with the fix for each.

First checks#

pablo system:doctor     # is every tool installed and logged in?
pablo task:list --live  # what GitHub and the tracker say right now
pablo sync:log          # what the last sync did, per project

Where the logs are#

You can also run a background job by hand to see its output: pablo system:poll [project], pablo sync:run [project], pablo sync:main [project].

Installation#

“Unable to write in the cache directory”#

A sudo pablo left files owned by root in PABLO's cache. Remove them once: sudo rm -rf app/var/cache (from the PABLO repository). The installer detects this and tells you.

pablo: command not found#

The installer writes the command to ~/.local/bin/pablo. Add ~/.local/bin to your PATH.

The doctor says an agent file is stale#

Your agents (in ~/.config/opencode/agents/, ~/.pablo/claude/agents.json and ~/.claude/agents/pablo-*.md under Claude Code, or ~/.copilot/agents/ under Copilot) were generated from older templates or an older project list. Run pablo system:generate-agents. A ❌ instead means a missing file, a broken link, or a file PABLO doesn't manage in its place.

Loading a project fails about default_model or pr_description_locale#

Both must be set, either in the project or in ~/.pablo/config.yaml. See global defaults.

The doctor says OpenChamber only works with OpenCode#

You set agent_runtime: claude-code (or copilot) with agent_backend: openchamber. OpenChamber drives its own OpenCode server and can't run Claude Code or Copilot, so nothing would launch; the background job refuses to run. Set agent_backend: orca (or remove it), or go back to agent_runtime: opencode.

Loading a project fails: default_model looks like an OpenCode provider/model id#

Under agent_runtime: claude-code, models are Claude aliases (sonnet, opus, haiku) or full model ids, not provider/model. Fix default_model and default_model_by_type in ~/.pablo/config.yaml and in the project files. Under agent_runtime: copilot, use Copilot's dotted ids (claude-sonnet-5.5, gpt-5.3-codex): provider/model ids and Claude Code names (sonnet, claude-sonnet-5-5) are refused too. See Choose the agent model.

Nothing happens after a reboot (Linux)#

User services only start at boot if your user “lingers”. The installer enables it; if it couldn't, run loginctl enable-linger $USER.

Agents#

An agent never started#

Orca can hang the first time it opens a brand-new worktree. PABLO notices when no agent session shows up in time and relaunches automatically, a limited number of times. To force it: pablo task:relaunch in the worktree (or --only=<agent>).

Agents run headless instead of in Orca#

Orca only sees repositories registered with it. Run orca repo add <repo path> for the project. Until then, PABLO runs the agents in the background; open those sessions with opencode -s <session>, claude --resume <session> in the worktree under Claude Code, or copilot --resume=<session> under Copilot (the session id is in the pid file in ~/.pablo/agents/).

The agents use the wrong model#

The model is chosen at launch: the project's default_model, then the one for its type, then the global one. See Choose the agent model.

States and pull requests#

The task stays in draft although CI looks done#

A pending check keeps the task where it is. If one never finishes (a manual deployment gate, for instance), exclude it with ci.ignore_checks. For a one-off, pablo task:skip-ci moves a ci-red task on.

A review didn't move my task#

Only some reviews count: not your own (replying to a comment creates a review in your name), not bots unless listed in review.bot_whitelist, and only those submitted after the pull request last became ready for review. A “changes requested” or a plain comment wins over approvals. Details in Task states.

An old “changes requested” is blocking the task#

Force the task past it: pablo task:state waiting-review or the state you want. See Force a state.

The QA failure label or status didn't trigger testing-failed#

• The project needs a testing.failure_signal, and testing.enabled must not be false.
• Only a new signal counts: a label added (GitHub) or a status reached (Jira, Linear) after the task entered needs-testing. A label that was already there doesn't.
• On Jira, PABLO sees status changes between two polls, so it can take up to state_polling.interval_minutes.

/pablo-commit-and-pr refuses to run#

It only works inside a PABLO task worktree, from in-progress, ci-red, request-changes, testing-failed, waiting-review or approved. With nothing to commit it stops on purpose (use --force if you committed by hand). If git has no identity configured, it stops with git's own error: set user.name and user.email.

A merged task doesn't disappear#

An agent is still running on its worktree: the task shows ✅ merged and closes on a later poll. To close it now: pablo task:close <branch> --yes.

Sync#

My branch wasn't rebased#

• Sync only reports by default: set sync.auto_apply: true or run pablo sync:run --apply.
• Branches with uncommitted changes are skipped (✋), and so are tasks busy with another PABLO operation (🔒, retried next time).
• Check what happened with pablo sync:log.

My main checkout wasn't updated#

PABLO only updates a primary checkout that is clean, has no local commits and isn't in the middle of a rebase or merge. pablo sync:main prints the reason for each project. See Primary checkout update.

Dashboard#

A task shows empty columns#

The dashboard and pablo task:list show what the poller last saved. A task the poller hasn't seen yet has nothing to show: run pablo task:list --refresh, or wait for the next poll.

The page doesn't load#

Check the service (systemctl --user status pablo-web.service, or launchctl print gui/$UID/com.pablo.web on macOS) or start it by hand with pablo web. Remember it only listens on 127.0.0.1.

Linear#

The Linear provider was written against schpet/linear-cli but hasn't been tested end to end yet. If a command fails, compare with linear --help; the calls live in app/src/Provider/Tracker/Linear.php.