Troubleshooting

Can’t find what you wrote, see an empty page, or a check passed and it still fails? Start with the closest item below.

The first time you use PowerContext, you are usually not stuck on an error message. You wrote something and cannot find it, the page looks empty, or doctor passed and recall still fails. The items below are cases already shown in 101. Pick the one that looks most like what you see, then follow its link.

Install flags, API contracts, and deploy settings follow the latest published official docs. This page only helps you name which kind of problem you hit.

1. Scope strings do not match

   The Client, Dashboard, Agent environment variables, and --scope-id must match exactly. Scope is a literal. project:powercontext-101 and project:powercontext-101:<uuid> are different Scopes. See Scope.

2. You changed the data directory or database URL

   A new POWERCONTEXT_HOME or database URL opens another database. That looks like a lost Scope. Check the data directory on Install and run the Server, then check Scope.

3. You treated 401/403 as empty

   empty means this Scope has nothing to recall right now. 401/403 is an auth failure. Do not inject context, and do not pretend there is no Memory. See fail-open and Connect with MCP.

4. Capture succeeded, search finds no Memory

   Capturing a Source records that something happened. It does not become durable Memory by itself. Without a generation model, the Source stays pending. Use remember_memory for a fact you already accept, or read Source and Memory.

5. Doctor passed, recall failed

   Check which command passed. powercontext doctor checks the package, whether the Server is up, and whether it is ready. powercontext doctor <host> only checks that Agent CLI and a limited install state. It does not probe the Server or send a real prompt. Verify the Server with the first command, then complete live recall on that Agent page. See the common agents overview.

6. The Dashboard is empty, but the data is there

   An unconfigured Dashboard Scope shows an empty page. Use the same scope_id as the Client, and keep the same database URL. Steps are on Verify Scope statistics in the Dashboard.

7. The Preview adapter will not install

   The Pydantic AI Agent adapter is Preview. Neither PyPI nor the current Git subdirectory install works. First integration is LangGraph or LangChain, not the Preview page.

8. You treated a bundled Skill as a managed export

   project-context is built-in Agent guidance. powercontext skill export is the managed Skill path. OpenCode, DSH, Pi, Hermes, and OpenClaw cannot export. See Let the agent extend itself.

9. You reused Candidate version as Artifact Revision

   Edits to a proposal use Candidate version. Approval creates an Artifact Revision. These are different numbers. Mixing them produces conflicts. See Let the agent extend itself.

10. You asked for a preview, then called Handoff

    handoff_current_work writes a boundary Source. Discussing a design, or saying preview and make no writes, must not call it. See Codex and Connect with MCP.

11. The Server is down, and you expected automatic recall to error

    Automatic recall, capture, and optional flush may fail open. The original task should continue. When you explicitly ask to write Memory, commit a Handoff, run Review, or export a Skill, the failure must be visible. See fail-open.

If PowerContext fails while automatically fetching context, keep working. If you explicitly write a Memory, commit a Handoff, approve a proposal, or export a Skill, you must see the failure. Read fail-open for the full rule.

Start with the closest match. Do not change several things at once.

Next step

Follow the learning path

Pick one path for your goal. Finish it before you decide whether to open the next.

Open the learning path

Start a local Server

Confirm the local Server and data directory before you treat this as a lost Scope or a new database.

Check the data directory