> ## Documentation Index > Fetch the complete documentation index at: https://jig.fapost.in/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Common problems and what to do about them. Start with `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. ## 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](/install#2-set-up-a-project)). For a single request, name the skill: `/jig-task` in Claude Code, `$jig-task` in Codex. | | 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. | | 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. | | Tasks that are merged but not closed | Say *"close what's merged"*; the agent asks you about each one. | ## Verification and upgrades | 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 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/.map`; each line needs a pattern and a decision ([Configuration](/configuration#a-verification-map-for-your-project)). | | `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. | | `upgrade` cannot determine the framework source | Pass `--from /absolute/path/to/jig`; an installed copy is not the full source. |