Troubleshooting

When integrating with PlanQ's JSON output, use the stable code, severity, reason, fix, and source range. Avoid parsing the localized display message, as it may change.

Installation

planq is not found

Confirm that the package manager's executable directory is on PATH, restart the shell, and rerun the platform's command from Install PlanQ.

PLANQ_NPM_NATIVE_PACKAGE_MISSING

Reinstall @planq-cli/planq without --no-optional. The wrapper requires the exact matching @planq-cli/linux-x64 package.

Editor integration

VS Code cannot start the language server

Run planq version in the environment used to launch VS Code. If the command works in a terminal but not in the extension host, set the machine-scoped plan.server.path setting to the executable's absolute path. Open Plan: Show Language Server Output and restart the language server after changing the setting.

The extension does not download the CLI. Keep machine-specific paths out of workspace settings.

VS Code preview does not open

The side preview supports desktop localhost sessions. Remote SSH, Dev Containers, and Codespaces do not have automatic port mapping and are rejected before the extension starts planq dev.

For desktop sessions, save the .plan file, verify the official PlanQ site is reachable, inspect the Plan Preview output channel, and run Plan: Restart Preview.

Emacs opens without tree-sitter highlighting

The major mode remains usable when the grammar is missing. Follow the grammar build and installation steps in Editor Integration, restart Emacs, and evaluate:

(treesit-ready-p 'plan t)

If the result is nil, confirm that libtree-sitter-plan.dylib on macOS or libtree-sitter-plan.so on Linux is in Emacs' ~/.emacs.d/tree-sitter directory or a configured treesit-extra-load-path.

Platform and libc

PLANQ_NPM_UNSUPPORTED_PLATFORM means npm is not the official channel for the current operating system or architecture. Use Homebrew on macOS arm64 or winget on Windows x86_64.

PLANQ_NPM_UNSUPPORTED_LIBC means the Linux runtime does not report glibc. Alpine and other musl systems are unsupported. Do not force-install the glibc binary.

Validation

Run:

planq validate project.plan

An exit code of 1 means the plan has errors—check the provided ranges and fixes. Exit 2 means arguments or file access failed, and Exit 3 means an unexpected internal failure. Warnings won't cause a valid plan to fail.

Common first checks:

• the document has one root map;
• IDs use ASCII kebab-case;
• task start and end dates appear together;
• references use @id;
• every referenced ID is visible in the entry include closure.

See Diagnostics.

Preview

If the browser does not open, use:

planq dev project.plan --no-open

Open the printed URL manually. If the page reports a Bridge failure, confirm the CLI process is still running, the URL has not been altered, and local loopback traffic is allowed. Stop stale sessions with Ctrl+C and start dev again.

Agent Skill

planq skill install refuses a conflict instead of overwriting it. Inspect the top-level canonical result.conflicts and the matching result.integrations[].conflicts from planq skill status. Preserve intentional project changes and resolve the reported path through normal Git review.

The managed locations are:

• .agents/skills/plan-gantt/ for the canonical payload and Codex discovery;
• .claude/skills/plan-gantt/ for Claude Code;
• .trae/skills/plan-gantt/ for TRAE.

A matching forwarder can be current while the canonical payload is missing or conflicting. The agent is usable only when both statuses are current. There is no --force, --agent, or global Skill installation option. Do not repair discovery by creating .codex/skills or a Skill under the user home directory.

GitHub sync

If manifest inspection fails, check your selected repository, branch, and path:

• for a selection or access error, correct the installation, repository, branch, or path and inspect again;
• for manifest/*, repair and validate plan.manifest.json locally, commit and push it, then inspect the new HEAD;
• changing any selection after a successful inspection requires another inspection before connection.

After connection, keep the stable ?setup=<bindingId> URL open. Refreshing restores persisted binding and source progress. A failed or disconnected binding stops waiting immediately. If synced or partial-failure completes without a valid source, use the displayed binding/source diagnostics, then choose Sync now or return to the connection configuration.

For source-missing, verify the bound manifest path at the configured branch HEAD. For disconnected, restore GitHub App repository access and reconnect the existing binding instead of creating a duplicate. For invalid, validate the same commit locally before requesting another sync. Stable code categories are listed in Diagnostics.

The GitHub App cannot repair or write repository content.

Get exact release information

planq version

Include the returned product version, build target, stable diagnostic code, and the smallest reproducible .plan excerpt when reporting a problem. Remove tokens, Bridge fragments, private repository names, and personal data first.