Troubleshooting

What you see, why, and what clears it. npx opencastle doctor names most of these itself, with the command that fixes each.

Commands

opencastle: command not found. npx opencastle init runs OpenCastle without installing it. Run every command the same way — npx opencastle sync — or install it once with npm i -D opencastle, which also pins the version for everyone.
Unknown command. npx opencastle --help lists the commands, and npx opencastle help <command> one command's options. A removed command says what replaced it.
unknown setting "…" in .opencastle/config.json. A misspelled key; the message suggests the one meant. Point your editor at the schema with "$schema" to catch it as you type.

CI and drift

sync --check fails on a pull request. A generated file no longer matches what its sources compile to. The report names each file and how it drifted: changed (edited by hand — make the edit in .opencastle/ instead), missing or outdated (sources changed without a recompile), or extra (a file added to a generated directory). Run npx opencastle sync on the branch and commit the result. On GitHub Actions each file is annotated in the pull request with its own fix.
A dependency bot's baseline bump fails the check. The new baseline compiles to different files, and the bot cannot recompile. Check out its branch, run npx opencastle sync, and push; npx opencastle review on that pull request says what the new version changes for this repository's assistants.
A file of yours disappeared after sync. It was in a directory OpenCastle generates, such as .claude/agents/ or .cursor/rules/; init and sync --check name such files before they go. Restore it from git and move it into .opencastle/ — instructions/, skills/<name>/ or agents/ — so it compiles for every assistant. A skill is the exception: one another tool wrote into a compiled skills folder — Devin proposes skills in .agents/skills/, Claude Code and Copilot write into theirs — is kept. sync moves it into .opencastle/skills/ and compiles it for every assistant; sync --check lists it under "Skills another tool added" until then.
A merge conflict in .opencastle/lock.json. The lock is generated. Resolve the conflicts in the sources, take either side of the lock, run npx opencastle sync, and commit the lock it writes.
An MCP server "needs fixing by hand". A server someone added to an MCP config that the team's policy does not allow, or that runs an unpinned or unknown package. sync cannot change a server it did not write; npx opencastle doctor names the server and what is wrong with it.

Versions and upgrades

This project was compiled by OpenCastle X; this is Y. You are running an older OpenCastle than the one that compiled the project, and compiling would take every teammate's files back. Run npx opencastle@X, or add OpenCastle to devDependencies so everyone runs one version. --allow-downgrade goes back on purpose.
A baseline is older than the one the lock records. Your node_modules predates a bump. Run npm install (or your package manager's), then sync.
A baseline cannot be found. An npm baseline must be installed: add it to devDependencies, and in CI install the dependencies before OpenCastle runs. A path in extends resolves from .opencastle/, so a baseline/ directory at the project root is "../baseline".
Upgrading. npm i -D opencastle@latest, then npx opencastle sync; it names each file it removes and counts the ones it changes, and git diff shows them all. Commit the result.

MCP servers and secrets

A server fails to start or to authenticate. It usually needs an environment variable. npx opencastle explain lists the ones you have not set, and which server needs each. Set them in your shell, or in .env at the project root — never in a committed file; init will not write into a .env the repository commits.
VS Code asks for a token. A token inside a remote server's header is a password input VS Code asks for once and keeps. A server's environment variables come from .env.
Codex does not load the servers. Codex reads .codex/config.toml only in a project you have marked as trusted. Trust the project when Codex asks.
A server asks you to sign in in a browser. Expected for servers that use OAuth (Linear, Notion, Supabase, Vercel and others): the first time it starts, then never again.

In your assistant

The /oc: commands do not appear. Restart Claude Code, or in VS Code run Developer: Reload Window. Cursor, Windsurf, OpenCode, Codex and Antigravity have no slash commands for them: ask for a prompt by name — "run the bug-fix prompt".
The assistant does not know the project. npx opencastle doctor says when .opencastle/project.instructions.md is still a template, and how much is left to describe. Run /oc:bootstrap-customizations, or ask for the bootstrap-customizations prompt.
An edit to project.instructions.md has no effect. It is compiled into what every assistant always loads. Run npx opencastle sync after editing it.
An agent tries to log its session and is told the command was removed. The project was compiled by an earlier release, whose instructions asked for it. Run npx opencastle sync.

Lessons

doctor: an assistant keeps memories the team does not have. The project is not compiled for the assistant its people work in — set up for VS Code, say, and used with Claude Code — so that assistant has no hook to share what it remembers and loads none of the lessons. Run npx opencastle init --customize and choose it as well.
What the agents remembered never becomes a lesson. The memory hook is written only for the assistants the project compiles for, and runs only in a folder the assistant trusts: accept Claude Code's or VS Code's workspace trust prompt. In VS Code, hooks are a preview feature, on unless chat.useHooks is off. Check the hook is there with npx opencastle sync --check, and run npx opencastle promote memory --dry-run to see what it would share. Memories saved as about you are never shared, by design.
doctor: a lesson cites code that has changed. Read the lesson against the code. Still true: npx opencastle lesson verify <id>, with --cite <new path> if the code moved. No longer true, or now in a skill: npx opencastle lesson archive <id> --into <file>.
promote memory finds no memory. It reads Claude Code's, VS Code's (Copilot Chat) and Codex's, once one of them has saved a memory about this repository; Codex's is off until you turn memories on. Cursor keeps its memories on its servers and Copilot Memory lives on GitHub, so neither can be read: ask the assistant to write what it learned with npx opencastle lesson instead.
doctor: the lessons index is large. Every agent reads it before every task. Move the lessons that keep coming up into the skill or instruction file they are about, and archive them there.
A lesson is refused. It names a category or severity that does not exist — .opencastle/LESSONS-LEARNED.md lists them — cites a file that does not exist (paths are relative to the project root), or would commit something that looks like a credential.

Convoy

The plan or the run cannot start an agent. A convoy runs on the agent CLI init set up — claude, codex, cursor-agent, opencode or copilot — which must be installed and signed in. --adapter <name> picks another.
The tasks do not see your latest change. Each task starts from the last commit. Commit before you run.
A run stopped, or failed part-way. npx opencastle convoy shows the last run and the one next step; npx opencastle convoy resume continues whatever is not done. npx opencastle convoy dashboard shows each task, its review and the checks.