Troubleshooting

Chat replies with the same canned text no matter what I type

WRITINGAGENT_FAKE is set in your shell - every model call returns placeholder text. The TUI shows a red warning at launch when this is the case.

Remove-Item Env:WRITINGAGENT_FAKE   # PowerShell

unset WRITINGAGENT_FAKE             # bash

writing-agent is not recognized

The console script is writing-agent, created by pip install writing-agent. If it’s not on PATH - common with Windows user installs - pip placed it in %APPDATA%\Python\Python3XX\Scripts; add that folder to your PATH and reopen your shell (or use pipx install writing-agent, which manages PATH for you). From a source clone you can also run python writingagent.py from the project folder.

401 Unauthorized on a real run

Check OPENROUTER_API_KEY in .env. To verify everything else without a key, use fake mode.

The web dashboard won’t open, or a run returns 409

writing-agent web binds 127.0.0.1 on port 8787 by default and auto-opens your browser - pass --port N if 8787 is taken, or --no-browser and open the printed URL yourself. It runs one background job at a time, so starting a second run while one is active returns a 409; wait for the first to finish (or stop it) and retry. It’s loopback-only with no auth, so it won’t be reachable from another machine - that’s by design.

A huge HuggingFace download started on a run

That’s the optional sentence-transformers embedding model (one-time, cached) - it only downloads if you’ve turned on semantic skill retrieval, since use_embeddings is off by default. Your writing still goes through your configured model host regardless. Don’t want it? /set use_embeddings false.

PDF export has no images / EPUB diagrams look odd

SVG diagrams render as vector art via svglib (always available). For full arrowhead fidelity install cairosvg. DOCX needs pandoc on PATH.

Writes are slow, or fail with PermissionError (WinError 32)

Two different causes:

• The export file is open in a viewer - close the PDF/DOCX and re-export.
• The repo lives in OneDrive/Dropbox - sync locks can break atomic writes. Set WRITINGAGENT_HOME to a non-synced folder; the brain + index move there.

A run stalled with “awaits review”

That’s manual mode doing its job. run shows the escalation picker; or answer with review --chapter N --instruction "..."; or go fully autonomous with /auto on (also clears the stalled review).

pip install fails on Linux building pycairo

You’re on an old checkout. The pin svglib<1.6 removed the pycairo build chain - git pull and reinstall.

Where do I see what a run cost?

/dashboard - total calls, tokens, real USD cost, latency, and errors, with a per-chapter/section breakdown per project. The live run dashboard also shows cost accruing in real time.