# Command line troubleshooting

> Page: https://docs.plotwork.dev/cli/troubleshooting. Index of every page: https://docs.plotwork.dev/llms.txt

What a message from the command line means and what to do about it. Most failures are one of the rows below.

## TL;DR

| Question | Answer |
|---|---|
| The check says a picture is stale, but I changed nothing | The pictures were drawn by another release or with other settings. Run `sync` with the release the check pins, and commit what it writes. |
| A glob matches nothing | Quote it, such as `"docs/**/*.md"`, and run from the repository root. |
| It says my Node is too old | Install Node 22 or newer. |
| Where do I see every option? | `plotwork <command> --help`, or the [Command reference](https://docs.plotwork.dev/cli/commands.md). |

## Stale pictures and drift

| Message | Cause | Fix |
|---|---|---|
| `stale: README.md needs sync` | The source of a fence changed and its picture did not, or the picture was drawn by another release or with other defaults. | Run `sync` on the file with the same release and settings as the check, and commit the Markdown and the SVGs. |
| `stale` in CI, `up to date` on your machine | The check pins one release and your machine ran another, or CI found a different settings file. | Run the exact command of the CI step, with its pinned version, from the repository root. |
| `drift: docs/infra.diagram` | The files a generated diagram is made from changed. The lines under it name each node and edge added, removed, or changed. | Run `generate` and commit what it writes. Change the diagram in its overrides file, never in the generated file. See [Diagrams as code](https://docs.plotwork.dev/diagrams-as-code.md). |
| A hand edit of a generated diagram is undone | `generate` writes over the generated file. | Run `generate --capture` after the edit, which moves it to the overrides file, then `generate`. |

## Usage mistakes, exit code 2

| Message | Cause | Fix |
|---|---|---|
| `no Markdown file matches docs/*.md` | The glob matched nothing from the working directory, or the shell expanded it first. | Quote the glob, and check the folder you run in. |
| `Unknown option '--colour'` | The option is not one the command takes. The help follows the message. | Run `plotwork <command> --help` for the options. |
| `no settings: add plotwork.config.json with a sources section` | `generate` found no settings file. | Add the file, or pass `--config <file>`. |
| `no rules: add a rules section to plotwork.config.json` | `check` found no rules. | Add a `rules` section, or pass `--org` with `PLOTWORK_API_KEY`. |
| A settings error with a line and a caret | The settings file does not check against its schema. | Fix the line it names. Add `$schema` to the file so your editor shows the mistake as you type. |
| `generate --out writes a report, so it needs --format json, sarif, or junit` | `--out` was given for text or github output. | Add a report format, or leave out `--out`. |

## Diagram mistakes, exit code 1

Each mistake has a code, a line and column, and a hint. The hint is the fix: apply it and run the command again. Every code is listed in [Diagnostics](https://docs.plotwork.dev/reference/language/diagnostics.md). `validate --strict` also fails on warnings, such as a label too long to read; leave out `--strict` to report them without failing.

## Installing and running

| Symptom | Cause | Fix |
|---|---|---|
| `plotwork needs Node 22 or newer` | An older Node runs the command. | Install Node 22 or newer, or use the `node:22` image in CI. |
| `npx` asks to install the package | `-y` is missing. | Add `-y` (or `--yes`) after `npx`, as every sample does. |
| `npm error 404` for the version | The version is not on npm, or a private registry does not mirror it. | Check the version on [npm](https://www.npmjs.com/package/@buun_group/plotwork), and mirror it into your registry. |
| A product icon is drawn as a plain shape | `PLOTWORK_VENDOR_ICONS=off` is set. | Unset it. See [Environment variables](https://docs.plotwork.dev/cli/environment.md). |

## Reading a picture

| Message | Cause | Fix |
|---|---|---|
| The picture carries no source | It was drawn with `--no-embed-source`, or by a tool that leaves the source out. `read` prints its title and labels instead. | Draw it again with the source embedded, or write the source again from the labels. See [Editing an existing diagram](https://docs.plotwork.dev/editing-existing-diagrams.md). |
| A hosted link cannot be read | The link is wrong, deleted, or private to an organisation. | Open the link in a browser to check it. |

## See also

| Doc | Why |
|---|---|
| [Exit codes and output formats](https://docs.plotwork.dev/cli/exit-codes-and-output.md) | What each code means for each command |
| [CI usage](https://docs.plotwork.dev/cli/ci.md) | The step for each CI system |
| [Configuration](https://docs.plotwork.dev/cli/configuration.md) | How the settings file is found |