Skip to main content
Start by checking the installed binary and live sessions:
Set PLANNOTATOR_DEBUG=1 for additional terminal diagnostics while reproducing a problem.

​
The command is not found

The macOS, Linux, and WSL installer writes the binary to ~/.local/bin/plannotator. If that directory is not on PATH, add it to your shell configuration and start a new terminal:
Use ~/.bashrc instead for Bash. Confirm the result with:
On Windows, the PowerShell installer adds its install directory to your user PATH. Restart the terminal after installation. Desktop agent applications may not inherit the same PATH as your shell. Restart the application, or configure its hook with the absolute path to the executable. A minimal install deliberately skips hooks, skills, slash commands, and sidecar tools. Run the full installer if you expected Plannotator to open from your agent.

​
The browser did not open

The server may still be running. Read the terminal URL or reopen it:
If the default browser command is wrong, select one for the current run:
You can also set PLANNOTATOR_BROWSER. On macOS it accepts an application name or path. On Linux and Windows, use an executable path. A BROWSER value such as none, false, 0, or : intentionally suppresses browser opening. If a stale session no longer responds, remove its record with plannotator sessions --clean and start a new review.

​
Plan review does not trigger

First restart the agent after installing or changing a plugin, hook, policy, or config file. Then check the host-specific trigger: Run a direct command such as plannotator annotate path/to/plan.md to separate a CLI/browser problem from a host-hook problem. If the direct command works, inspect the agent’s hook log and verify that its process can find the binary.

​
Remote SSH and development containers

Confirm that the agent process inherited both remote settings:
With the default remote port, forward the session from your local machine:
Setting PLANNOTATOR_PORT alone does not make a container session reachable. PLANNOTATOR_REMOTE=1 changes the bind address from 127.0.0.1 to 0.0.0.0.
Remote mode exposes an unauthenticated HTTP server on 0.0.0.0. Do not publish the port or bind it to an untrusted network. Use SSH forwarding or a trusted private development environment.
Follow Remote access for the SSH command, development-container configuration, direct private-network access, verification steps, and remote-sharing boundary. The embedded agent terminal is disabled in remote mode by default.
Set PLANNOTATOR_AGENT_TERMINAL_REMOTE=1 only on a trusted connection. This setting enables command execution through the forwarded UI.

​
A port is already in use

Local sessions normally choose a free random port. Remote sessions default to 19432. Pick another fixed port or let Plannotator try a range:
A fixed port is retried five times for a transient conflict. A range advances immediately to the next available port. An invalid port value prints a warning and falls back to the normal default.

​
GitHub pull request or GitLab merge request review fails

Plannotator uses the matching host CLI. Install and authenticate it before opening the review:
Use gh for GitHub pull requests and glab for GitLab merge requests. For an enterprise host, authenticate the same hostname used in the URL. By default, Plannotator prepares a local checkout for full file access. If cloning or checkout preparation fails, use diff-only mode:
Diff-only mode cannot provide every local file or repository operation. For local changes, run plannotator review from inside the repository and confirm that the working tree has a supported VCS.

​
Local HTML does not render correctly

Local HTML renders raw by default. Do not add the old --render-html flag; it is retained only as a compatibility no-op. Relative images, stylesheets, scripts, fonts, media, and other supported assets are served from the HTML file’s directory. Plannotator refuses paths outside that directory, unsupported asset types, missing files, and files over the asset-size limit. Check the browser network panel for 403, 404, 413, or 415 responses and make the document self-contained when practical. To review the document’s text instead of its rendered page, convert it to Markdown:
Raw HTML is rendered in a sandboxed iframe, but its scripts can still run inside that frame. Review only HTML you trust.

​
URL annotation fails or shows poor content

Plannotator first accepts native Markdown when a site serves it, then uses Jina Reader by default for public HTML. If Jina fails, it warns and falls back to direct fetch and local conversion. Force the direct path when a site works better without Jina:
Local and private-network URLs skip Jina automatically. Public URLs that redirect to a private or local address are blocked. Fetches time out after 30 seconds and responses are limited to 10 MB. Authentication cookies from your browser are not sent, so save a protected page locally before annotating it. If Jina rate limits the request, set JINA_API_KEY or use --no-jina.

​
A local annotation file is too large

Single-file and folder annotation accept local files up to 2 MiB. A larger file fails with File too large to annotate (max 2MB). Reduce or split the file before reopening it. In a strict annotate --gate --json workflow, this startup failure exits 2.

​
A large untracked file appears as binary

Code review loads and diffs untracked text files up to 5 MiB. An untracked file over that limit appears as a binary addition and Plannotator refuses to load its contents. Exclude, reduce, or commit the file if you need to inspect it through another comparison.

​
Sharing fails

Check whether sharing is disabled:
PLANNOTATOR_SHARE=disabled overrides config.json for integrations that use Plannotator’s shared configuration resolver. OpenCode checks an explicit OpenCode share setting first, so set that value to "disabled" as well. For other integrations, remove the environment variable or set an enabled value for a new session when sharing is intended. Markdown share links can carry compressed content in the URL fragment. Raw HTML sharing uses an encrypted paste service so local assets can be included. If raw HTML sharing fails:
  • check network access to the paste service
  • check PLANNOTATOR_PASTE_URL if you configured a custom service
  • remove unnecessary assets or make the HTML smaller and self-contained
The decryption key remains in the URL fragment. Anyone with the complete link can open the shared content, so treat the link as sensitive.

​
Config changes are ignored

Confirm that you edited config.json in the active data directory. Plannotator chooses that directory in this order:
  1. PLANNOTATOR_DATA_DIR, with leading ~ expansion
  2. An existing ~/.plannotator
  3. $XDG_DATA_HOME/plannotator when XDG_DATA_HOME is absolute
  4. ~/.plannotator
An existing ~/.plannotator wins over XDG. A relative XDG_DATA_HOME is ignored, and Plannotator does not implicitly use ~/.local/share. If PLANNOTATOR_DATA_DIR is relative, Plannotator resolves it from the working directory where that process launched. The installer, agents, and shells can use different directories for the same value. Make sure that you inspect every working directory, not only the environment variable. Malformed JSON produces a warning and Plannotator uses defaults. Validate the file with a JSON parser. Remember that command flags and environment variables override config.json for the settings they control. The Settings panel also uses a browser cookie. Server-synced fields prefer config.json; interface-only fields live only in the cookie. Clear site data for localhost if a cookie-only setting is stuck, but note that this resets other Plannotator UI preferences in that browser.

​
Cursor review jobs fail to start

Cursor review jobs use Ask mode and pass --sandbox enabled by default. On systems where Cursor’s sandbox cannot start, including some NixOS or AppArmor-restricted Linux setups, retry without the forced sandbox:
For a persistent setting, add "cursorSandbox": false to config.json. Plannotator then omits the sandbox flag and defers to your Cursor Agent configuration. Write protection depends on --mode ask and your Cursor settings in this mode.

​
AI panels are missing

Check for an explicit kill switch:
PLANNOTATOR_AI=disabled removes Ask AI, Review Agents, and Guided Review and disables their provider and job endpoints. Remove it or set another value, then start a new session. Ordinary reviews and external annotation submission still work.

​
Ask for help

When reporting a reproducible OSS issue, include:
  • plannotator --version
  • operating system and agent name/version
  • the command you ran, with secrets and private URLs removed
  • terminal output with PLANNOTATOR_DEBUG=1
  • whether the direct CLI command works outside the agent hook
Report issues at github.com/backnotprop/plannotator/issues. Last verified against Plannotator OSS v0.25.1 on July 31, 2026. Maintained by the Plannotator project.
Last modified on August 13, 2026