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

Use a fixed forwarded port and force remote mode:
For SSH, forward the same port to your machine:
Open http://localhost:9999 locally while the review is running. For a development container, set the variables in containerEnv and include 9999 in forwardPorts. 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.
The embedded agent terminal is disabled in remote mode by default. PLANNOTATOR_AGENT_TERMINAL_REMOTE=1 enables command execution through the forwarded UI and should only be used on a trusted connection.

​
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 is the problem, try 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.

​
Sharing fails

Check whether sharing is disabled:
PLANNOTATOR_SHARE=disabled overrides config.json and hides sharing. Remove it or set an enabled value for a new session. 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 the active data directory:
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.

​
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.23.1 on July 18, 2026. Maintained by the Plannotator project.
Last modified on July 19, 2026