Troubleshooting

Each problem below starts with what archgram says, or what you see, then what it means and what to do. archgram's messages name the file, the line and the column, so most fixes start there.

archgram could not find @archgram/cli-…#

archgram could not find @archgram/cli-darwin-arm64, the package with its binary for this machine. npm leaves it out when optional dependencies are omitted (--omit=optional, --no-optional), or when package-lock.json was written on another platform (npm/cli#4828). Reinstall with optional dependencies: delete node_modules and package-lock.json, then run npm install.

archgram is a native binary, which npm installs from an optional dependency for your system. It is missing when optional dependencies were left out, or when the lockfile was written on another system. Delete node_modules and the lockfile, then install again without --omit=optional. To use a binary you have elsewhere, point ARCHGRAM_BINARY at it.

is not a logo archgram carries#

docs/diagrams/architecture.archgram.yaml:6:54: `postgres` is not a logo archgram carries; did you mean `postgresql` (PostgreSQL)? If not, leave `tech` out

tech takes a logo's name as Simple Icons spells it. Use the name it suggests, or leave tech out and the card keeps its icon.

no node has the id#

docs/diagrams/linkshort.archgram.yaml:10:22: no node has the id `dbx`; did you mean `db`?

An edge, a flow, a frame or a hint names an id no node has, usually a typo. archgram suggests the nearest id.

no edge goes from … to …#

docs/diagrams/linkshort.archgram.yaml:12:44: flow `a visit` goes from `api` to `db`, but no edge goes from `api` to `db`

Each step of a flow must be reached by an edge from the step before it. Add the edge, or fix the step. Show how a request moves has the rules.

did not find expected ',' or '}'#

docs/diagrams/architecture.archgram.yaml:5:1: while parsing a flow mapping, did not find expected ',' or '}'

The YAML itself is broken, usually a { … } that is not closed or a missing comma. The line archgram names is often the one after the mistake.

does not hold …#

docs/diagrams/architecture.archgram.yaml:8:37: edge worker → db: `../../src/worker.ts` does not hold `db.insert(order)`

A source's words are no longer in its file, so the code behind that part or line changed. If the code moved, point the source at its new place. If it is gone, remove the part or the line. check fails on this, and build only warns and still draws. Keep a diagram true explains sources.

the drawing is … px wide#

archgram: warning: docs/diagrams/architecture.archgram.yaml: the drawing is 2267 px wide, wider than the 1300 px a README on GitHub shows at a readable size; write `direction: down`, which draws it 249 px wide, or split it in two

The drawing is too wide for its text to stay readable where it is shown. Write the direction it suggests in the spec, or split the diagram in two. If it is not shown in a README, set shownWidth to the width of the place it is shown. The drawing is still written, so this never stops you.

A source with # loses its words#

In YAML, a space before # starts a comment, so an unquoted source loses everything after it. Quote every source that holds a #.

source: "../../src/api.ts#app.post("

The drawing does not follow GitHub's theme#

One SVG follows the reader's system, not the theme picked on GitHub. Draw with --split-themes and show the two files in a <picture>. Put it in a README or a site shows how.

The drawing does not move#

If your system is set to reduce motion, the drawing shows its still image on purpose. Set still in the spec so the still image tells the flows too. Show how a request moves explains it.

Text crowds or overflows a card#

archgram measures text with Geist, the font it embeds. With --system-font the reader's font draws the text, and a wider one can crowd a card. Draw without --system-font.

npx asks to install archgram#

npx asks before it downloads a package the project does not list. Add archgram to the project, as in the Quickstart, and it runs the project's own.

Still stuck#

Open an issue with the command you ran, what it printed and your spec.