Troubleshooting

Every error starts with Error: and says what to do next. This page explains the ones you're most likely to see.

No Session Found

Error: no PAS-Agent session found in /home/me/project or any parent directory; run `pas-agent init` first

Commands look for .pas-agent/session.json in the current directory and then in each parent directory. Either you're outside the project, or no session exists yet. Change into the project, or run pas-agent init.

A Session Already Exists

Error: a PAS-Agent session already exists at /home/me/project/.pas-agent/session.json

Each project has one session. To change the task, usepas-agent update --task "...". To start over, delete .pas-agent/(or move it away) and run init again.

The Session Is Locked

Error: the session is locked by another pas-agent process (.pas-agent/session.lock); retry in a moment

Another pas-agent command, often from a second agent, is updating the session. Commands wait up to 5 seconds, so a running command took longer than that. Retry. The lock is released by the operating system when the holding process exits, even if it crashed, so there is nothing to clean up and you should not delete session.lock by hand.

Warning: The Exported Context Is Too Long

⚠ AGENTS.md is 14211 characters, but antigravity reads at most 12000 of a rules file, so the end may be cut off.

Antigravity ignores everything past 12,000 characters of a rules file. The size counts the whole file, including your own content outside the PAS-Agent block. The export is still written. Shorten the session with pas-agent remove <list> <N>, for example by removing old completed items. Other agents have no known limit, so they never show this warning.

Damaged Session File

Error: .pas-agent/session.json is not a valid session file: EOF while parsing an object at line 2 column 0
The session file is damaged. Fix the JSON by hand or restore it from git.

PAS-Agent writes the file atomically, so this usually comes from a hand edit or a merge conflict. The message gives the line and column. Fix the JSON there, or restore the last good version with git checkout -- .pas-agent/session.json if you commit it.

Session From a Newer Version

Error: .pas-agent/session.json uses session schema v2, but this build supports up to v1; upgrade pas-agent

The file was written by a newer PAS-Agent, for example on another machine. It's rejected instead of being misread. Upgrade PAS-Agent on this machine.

Broken Marker Block

Error: AGENTS.md has a PAS-Agent start marker without a matching end marker (or vice versa); fix it by hand or re-run with --force

Export only replaces the text between <!-- pas-agent:start ... --> and<!-- pas-agent:end -->. If one marker was deleted, PAS-Agent can't tell where the block ends, so it changes nothing. Open the file, delete the rest of the old block, and export again.

--force also works, but it replaces the whole file, including your own instructions. Use it only if the file holds nothing else you want to keep.

Invalid Item Number

Error: no item #3 in remaining (it has 2 item(s); run `pas-agent status` to see numbers)

Numbers refer to what pas-agent status shows right now, and they shift after items are removed. Check status and try again. If any number is invalid, nothing is changed.

Nothing to Update

Error: nothing to update; see `pas-agent update --help`

update needs at least one flag that changes something, such as--completed or --next. See theCLI Reference.

Unknown Agent

error: invalid value 'foo' for '--to <TO>'
  [possible values: claude-code, codex, opencode, kiro-cli, antigravity, gemini-cli, cursor]

Use one of the listed targets (aliases like claude, gemini,kiro, and agy also work). For an agent that isn't listed, export tocodex if it reads AGENTS.md, or write anywhere with--output.

No Git Information

If init prints no Git: line and checkpoints show no commit, the project isn't a git repository, or git isn't on your PATH. PAS-Agent still works without git; it just can't record branches, commits, or changed files. Run git --versionto check.

The Agent Ignores the Context

Check that the file was written where the agent looks: the project root, with the name from thetable of files. Agents read these files when a session starts, so restart the agent after exporting. If it still doesn't act on it, say so directly: "read the PAS-Agent session context in AGENTS.md and continue".

Upgrade

Download the new archive from thelatest releaseand replace the binary, or reinstall with Cargo:

cargo install --force --git https://github.com/gfirik/pas-agent pas-agent-cli

Existing session files keep working. Newer versions read older files.

Uninstall

# Installed with Cargo
cargo uninstall pas-agent-cli

# Installed from a release archive: delete the pas-agent binary you put on your PATH

To remove PAS-Agent from a project, delete .pas-agent/ and the block between thepas-agent:start and pas-agent:end markers in your instruction files.