Not sure what went wrong?
Copy the error message into your AI chat and say:Send to your agent
Help me fix this before continuing the task.
Explain what happened, what you need from me, and how we will check the fix.
Include what you were trying to do and the last command or action. Remove passwords, API keys,
and other private values before sharing an error message.
jig doctor. It checks the machine, the project and your agent’s instructions, one line
each, and prints a fix for every warning. On Windows, run it in Git Bash, or as
.ai\scripts\jig.cmd doctor in PowerShell.
If the trouble turns out to be Jig itself rather than your project, see Known issues
— the faults we know about, and what to do instead of each.
The agent does not follow Jig
| Symptom | What to do |
|---|---|
| The agent works without classifying the task or creating one | Your AGENTS.md or CLAUDE.md probably lacks the Jig section — jig status shows instructions (...): no Jig section. Ask the agent to “connect Jig to my AGENTS.md”, or add the section by hand (Install). For a single request, name the skill: /jig-task in Claude Code, $jig-task in Codex. |
| Jig’s own instructions never seem to improve | Your AGENTS.md probably carries the Jig section without its markers — jig status shows instructions (...): Jig section in AGENTS.md is not marked. jig upgrade reports it as keep-unmarked AGENTS.md and changes nothing. Ask the agent to “connect Jig to my AGENTS.md” and keep the <!-- jig:begin --> / <!-- jig:end --> lines it adds. |
jig upgrade says keep-modified AGENTS.md (Jig section) | Someone edited inside the markers, so Jig keeps your text and stops updating that section — by design. To go back to the maintained version, replace the region between the markers with the one in .ai/templates/AGENTS.md. |
| The skills are missing in the runtime | Check that the runtime is listed under adapters in .ai/config.yaml, run jig upgrade, and reopen the agent session. |
| The agent does not know a rule your team wrote down | The document may still be proposed — jig status shows the count on its proposals: line. Ask the agent to “review the proposals”. |
Installation
| Symptom | What to do |
|---|---|
jig: command not found | Open a new terminal — the installer’s PATH change reaches only new ones. Otherwise check that ~/.local/bin (or, on Windows, the Jig scripts folder) is on PATH. |
| Something does not work on Windows | Run jig doctor and follow each fix: line; the installer’s log is %LOCALAPPDATA%\jig\install.log. |
self-update refuses | Commit or stash the changes in the Jig checkout. A developer checkout on a branch without an upstream is updated with Git directly. |
framework versions: ... global=unavailable | There is no Jig on PATH, or it is not a full checkout. Harmless in CI; install it where you update from. |
Projects and tasks
| Symptom | What to do |
|---|---|
not inside a git repository | Change into the project, or make the folder a Git repository first. |
project is not initialised | Run jig init in that repository. |
the repository has no commits yet when starting a task | Commit what jig init added, then start again. |
| Starting a task refuses because of uncommitted changes | They belong to other work. Pause the task that owns them (“pause it and stash the changes”), or start the new one in a separate worktree. |
--worktree needs a directory link | The disk supports neither symbolic links nor NTFS junctions (a network or FAT drive). Keep the project on a local disk, or start the task in the current checkout. |
Filing a task refuses: this worktree keeps a tasks/ folder of its own | A worktree started by Jig shares the project’s task list, so a task filed inside it lands with all the others. A worktree you made yourself with git worktree add does not, and neither does one in a project whose ignore rule ends in .ai/workspace/tasks/ — a task filed there would be invisible to the project and would go when the worktree went. The message names the checkout to file it in. |
| Several tasks match the branch | Tell the agent which one to continue. |
wrong-base in the housekeeping report | A task’s pull request was merged into a branch other than its base. It is kept; check where the work went. On the staging flow a pull request merged into the staging branch is not flagged: the task shows as on staging instead. |
task/<id> carries <n> commit(s) that main does not have, through a merge of … | Something other than the base branch or a clean task branch was merged into the task branch — the staging branch, another branch, or a task branch that itself carries staging; the message names it. A task branch stays clean until it reaches the base: rebuild it from its own commits on the base branch and ship again. A conflict with staging is resolved on staging, when the task lands. |
jig task land stops with exit 5 | The pull request conflicts with the staging branch. Resolve the listed paths in the temporary worktree it names, git add them, and run jig task land <id> --resolved --note-file <file>; --abort gives the landing up. |
not landed: origin refused the push to staging | The staging branch does not take a direct push from you (a protected branch, a hook). The merge with the resolution waits in the temporary worktree: push it with rights that are allowed, or land the pull request on the forge; jig task land <id> --abort removes it. |
| Tasks that are merged but not closed | Say “close what’s merged”; the agent asks you about each one. |
| The status page does not change | Look at the time at its top. If it is recent, nothing changed. If it is old, you may have an older copy open — open it again with jig status --open; in Firefox, automatic reloading can be turned off by the setting accessibility.blockautorefresh. |
jig housekeeping says <id> was not archived: … and exits 3 | The task could not be archived; the message after the colon says why — for example its notes could not be written (a read-only folder, a full disk). The task is kept as it was; fix the cause and run jig housekeeping again. |
The pull request was not opened: must be a collaborator, or the agent asks you to switch your GitHub account | You are signed in to gh with several accounts and the wrong one is active. Do not switch: Jig finds this project’s account by itself. If it still fails, tell it which one — add github.account: <login> to .ai/config.local.yaml. See Two GitHub accounts. |
several gh accounts may push to … | More than one of your accounts may write to this repository and the active one is not among them, so Jig cannot choose. A push over HTTPS, or a ship at agent.git: pr or merge, stops before it sends anything; over SSH at agent.git: push your key decides and the push goes on. Say which is this project’s: jig config set --local github.account <login>. |
refusing to allow an OAuth App to create or update workflow … without workflow scope | The change touches a file under .github/workflows, and the gh token of the account Jig pushes as lacks the workflow scope. Add it to that account, as Two GitHub accounts describes, and run the ship again; the commit is still on this machine. |
github.account is …, and gh gives no token for it | The account named in .ai/config.local.yaml is not signed in to gh on this machine. Sign it in with gh auth login, or change the name. |
task set: status consolidated requires its pull request to be merged: … is unknown, the forge could not be asked (…) | Jig could not ask GitHub or GitLab whether the pull request merged; the reason is in the parentheses — gh or glab missing or not signed in, an error, no answer in time. The pull request may well be merged. Fix the cause and run the same command again. |
task set: <id> is on <staging> and not in <base> yet: … | On the staging flow a task’s work reaches the base only through its promotion, so the close waits for it, even when the pull request into staging merged. Prepare for prod (jig task promote <id>), wait for the promotion to merge, fetch (or run jig housekeeping), then close the task again. When the message says the forge could not be asked, fix the cause and run the same command again. |
task set: <id> is pushed and not in <base> yet: … | The task’s branch is pushed but has not landed on the staging branch yet (under git.staging_land: external CI lands it). Wait for the landing, prepare for prod, and close the task once the promotion merged. |
task start: <id> has no goal (a warning) | The ## Goal section of the task’s task.md is empty, so the work would begin on an empty template. Write the goal with jig task artifact write <id> task --from <file>. For a T3 or T4 task it is a refusal (task start: <id> is T3 and has no goal): write the goal first, then start again. |
task abandon: <id> is linked to spec <sid>; say why | A task that a specification’s roadmap points at is not given up silently. Run jig task abandon <id> --reason <text>, and add --moved-to <repo>#<task-id> if the work went to another repository (Giving a task up, or moving it elsewhere). |
task abandon: --reason must be a single line with no tab | Put the reason on one line, without a tab character. |
jig task ship prints warning: N open finding(s) not handed over: … | The pull request was opened; only the hand-over of the review’s open P2/P3 findings to a triage task failed, and they are still in the pull request’s body. The text after the colon says why: the triage task <id>-findings already exists and is not this task’s triage, <id>-findings is not a valid task id, or filing it with jig task new was refused for the reason quoted. Fix that, or file the findings yourself (Review findings). |
| The status page says pull request data is stale | Run jig housekeeping; it asks GitHub or GitLab again. |
Verification and upgrades
upgrade: cannot determine the framework source root; pass --from <dir> in a project on Jig
0.38.1 or older usually means .ai/manifest has a jig.source: line naming another person’s
folder. The project’s own copy cannot get past it — nor can your agent, or a jig shell function
or alias that runs that copy. Run the upgrade once with the Jig on your machine, by its full path,
in the project’s root folder. macOS and Linux:~/.local/bin/jig self-update
~/.local/bin/jig upgrade
~/.local/share/jig/scripts/jig self-update
~/.local/share/jig/scripts/jig upgrade
.ai/manifest says jig.source: global when that Jig is the one on your PATH (else
it names its folder), and a plain jig upgrade works. More in
Upgrading.| Symptom | What to do |
|---|---|
| Verification reports skips | The project’s tools are missing — install its dependencies (npm install, composer install, a virtual environment …) and run it again. A skip is not a pass. |
| Verification says nothing was checked, so this is not a pass, and exits 3 | A profile for your stack is active but none of its checks could run — its tools are missing. Install them (npm install, composer install, a virtual environment, shellcheck …) and run it again; jig verify --list shows which profiles are installed. Until then jig task ship will not ship, because there is no evidence to ship on and something can be done about it. |
| Verification says nothing here checks this project, and exits 0 | No profile covers this project, so there is nothing to install and nothing to wait for. Jig does not stop you — but nothing verified this change, and jig task ship says so again as it ships. If your stack has a profile, activate it in .ai/config.yaml; if it has none, the checks are yours to add. |
| Verification says every check in scope skipped, and exits 0 | Your stack’s profile is active and its tools are fine — this change simply does not touch anything within its scope, a documentation-only edit beside a shell profile, say. There is nothing to install and nothing to wait for; --changed narrowed the run to nothing on purpose. The full set still runs in CI. |
| Verification reports incomplete, and exits 3 | The run was killed rather than failing — usually because the machine ran out of memory or was overloaded. It is neither a pass nor a failure: run it again. If it keeps happening, run fewer things at once, or narrow the run. |
| Verification says it is waiting for another run | Another jig verify is already going in this clone — in this checkout or in one of its worktrees — and running both makes both slower. It goes ahead as soon as the other finishes, and says how long it waited. To never wait, set verify.busy_ttl: 0 in .ai/config.local.yaml. |
| Verification refused: this project looks like it runs in a container, and exits 3 | Jig saw a sign of a container — a DB_HOST naming a compose service, two services mounting the project, a .devcontainer/ or .ddev/ folder without its manifest … — and no detector it knows recognised it, so it would not run the checks on this machine. Run the jig-setup skill, or set run.exec yourself: the command that reaches the container, or host if this machine is right (Where checks run). |
| Verification refused: the environment is not running | Start it with the command the line names (./vendor/bin/sail up -d, docker compose up -d, ddev start, lando start, devcontainer up --workspace-folder .) and run it again. |
| Verification refused: the environment does not see this checkout | You are in a task’s worktree and the container mounts another copy of the project. Start an environment from the worktree, or verify in the checkout the container mounts. |
| Checks run in the wrong place | jig verify --explain prints where they run and why. Set run.exec in .ai/config.local.yaml — or ask the agent to run jig-setup — to override what Jig detected. |
upgrade: the source is not a release: … is on branch main at <sha> (also from jig init) | The Jig on your machine is a checkout on a branch or past its release tag, and a project that keeps Jig’s files in its own repository takes released code only. Return it to a release with the git -C … checkout v<version> the message prints, or take the code on purpose with jig upgrade --unreleased. See Upgrading. |
upgrade: the source is not a release: … is at its release tag with uncommitted changes (also from jig init) | Files in the Jig on your machine were edited or added after it was installed, so it no longer holds the release’s bytes. See them with git -C ~/.local/share/jig status --short and put them away (git -C ~/.local/share/jig stash -u), or take the code on purpose with --unreleased; the project then records X.Y.Z+<sha>.dirty. |
jig status shows global=X.Y.Z+<sha> and the hint the global jig is on the development channel | The Jig on your machine is on a branch; +<sha> marks unreleased code. Projects will not upgrade from it. Return it to a release (git -C ~/.local/share/jig checkout v<version>) or develop Jig in a clone of its own. jig verify does not demand pending framework files from such a source. |
| Verification refuses: framework files pending | Run jig upgrade --dry-run, then jig upgrade, review the change, and verify again. |
| A map line fails a profile | The error names the file and line in .ai/verify/<profile>.map; each line needs a pattern and a decision (Configuration). |
upgrade kept some files | You edited them; the report marks them keep-modified or keep-conflict. Compare with the new version and reconcile by hand. A file marked already-placed needs nothing from you: it already holds this version’s bytes, and the run has just recorded that. |
jig status reports drift on framework files right after an upgrade | The upgrade was carried out by the version being replaced, which recorded the hashes the way it computed them. Run jig upgrade once more: the new code recognises the files as already placed, records them, and the drift goes. Nothing is wrong with the files themselves. |
upgrade says N item(s) still not installed | The run asked the install it had just made, and something is missing — usually because the upgrade was carried out by the older version, which did not know about every file the new one ships. Run jig upgrade again; the second run is done by the new code and finishes the job. |
upgrade cannot determine the framework source | The project’s copy found no Jig to copy from: it is not a framework checkout, there is no jig on your PATH, and the source .ai/manifest records is not on this machine. Install Jig (Install), or pass --from /absolute/path/to/jig. A project on Jig 0.38.1 or older also stops here, with upgrade: cannot determine the framework source root; pass --from <dir>, when the manifest names another person’s folder: see the red box above this table. |
upgrade says manifest unchanged | It placed nothing, so the project stays on the checkout it was installed from. To move it onto the one you passed, run jig init --from <dir> (add --link in link mode). |
upgrade --land: the pull request of <branch> is not merged yet (<url>) | The upgrade’s pull request is still open, and nothing was changed. Merge it, then run jig upgrade --land again (An upgrade is a change of its own). |
upgrade --land: nothing was changed: followed by - ... lines | Each line is one reason, and all of them are listed at once. Act on each: commit or stash uncommitted changes (they matter only on the base or the upgrade’s branch: from another branch the checkout is not touched), run it in the worktree the base is checked out in when it is checked out elsewhere, push or reconcile commits the base has that origin/<base> does not, and fetch when origin/<base> is not known or does not yet hold the merged upgrade. Then run jig upgrade --land again. |
upgrade --land says this is a linked worktree on <branch>, and Jig never switches one to <base>; run jig upgrade --land in the main checkout | Jig never moves a linked worktree onto the base branch. Run jig upgrade --land in the main checkout, the folder the message names. |
Writes on a branch of their own
A change to a roadmap or a decision on knowledge, made from a program or withjig writes ship, is
committed on a branch of its own (Writes on a branch of their own).
When Jig refuses it, the refusal has a code; nothing was written.
| Code | What it means | What to do |
|---|---|---|
git-not-allowed | agent.git is none in this clone, so Jig commits nothing. | jig config set --local agent.git commit (or push, pr, merge), or make the change in an agent session. |
write-busy | Another write holds this clone’s lock (another write is running in this clone, another write just started), or has the tree at <git-dir>/jig/tree (another write has the tree at <path>). | Try again in a moment. The lock is taken back by itself when its holder is gone. It lives in .ai/runtime/writes/lock of the clone’s main checkout, or, with --separate-git-dir, in a submodule, or in worktrees of a bare repository, under <git-dir>/jig/writes/lock. When the message says another write is taking back a lock, and it keeps saying so, delete the file it names: a busy/clear.… claim in that lock folder, left by a write that stopped part-way. |
branch-checked-out | The write’s branch is checked out in a worktree (the message names it). | Finish the work there or switch that checkout to another branch; Jig never moves a checkout. |
branch-has-other-commits | The branch holds commits of yours that no Jig write made and origin does not have. | Push or merge them yourself, or move them to another branch. Jig does not publish them. |
base-not-on-origin | The base branch is not on origin, so no pull request could open into it. | Push the base branch yourself. |
write-still-waits | An earlier edit is still waiting: it never reached origin, its pull request was closed unmerged, or it waits to go into another base. | Merge or close what waits (jig writes ship <target> carries it on), or move its commits to a branch of your own with git branch -m <branch> <name>; then try again. |
tree-in-the-way | A write that did not finish left a folder where Jig makes its tree, and git will not remove it. | Delete the directory the message names (<git-dir>/jig/tree), then try again. |
Reviewing a colleague’s pull request
These come fromjig pr, used by the jig-pr-review skill (Skills).
In each, nothing was posted.
| Symptom | What to do |
|---|---|
pull request <n> moved since it was reviewed (GitHub), or merge request <n> moved since it was reviewed (GitLab), ending fetch it again and review what changed — nothing was posted | The author pushed after the review was made, so its comments might no longer fit the code. Run jig pr fetch <url> again and review what changed. |
the conversation of pull request <n> is locked / the discussion of merge request <n> is locked, and the account is not a member who may still comment | The thread is locked and the account the review posts as may not comment on it. Ask the repository to unlock it, or post as an account that may comment. |
the GitHub CLI (gh) is needed, or the GitLab CLI (glab) is needed | Install the CLI for the forge the link points at, and sign in to it. |