# Troubleshooting

Start with what you see. Follow the checks, then confirm that your agent can read the right project.

These checks are for the current local setup. Repository access, a local server and a signed-in coding client are required.

## What are you seeing?

### Can’t reach server: Start with the local connection.

Connection refused

The client needs a running Prickle server on the same computer. Confirm reachability before changing any credentials.

1. **Check the address**

Use http://127.0.0.1:8787/mcp for the default local MCP server. Keep the terminal running the server open. The web app’s address is different.

2. **Ask the server if it is alive**

Read-only terminal check

```text
curl -i http://127.0.0.1:8787/healthz
```

Expected: HTTP 200 and “ok”. This checks the server, not the token or project access.

3. **Test a real tool call**

Once the server answers, start a fresh client session and ask your agent to read project context. Seeing the server listed in settings is not enough.

**What working looks like:** The client can call get_project_context and read the intended project.

[Review the local setup](https://app.useprickle.dev/docs/quickstart?path=local)

### Token rejected: Check the Prickle token and its server.

401 · Unauthorized

A 401 means the MCP request did not authenticate. The token may be missing, invalid or revoked.

1. **Check the header shape**

Configuration shape · placeholder only

```text
Authorization: Bearer <prickle-agent-token>
```

Include Bearer, a space and the token. Never use your AI provider login here.

2. **Use the same database**

The token must be minted against the database the MCP server is using. A web-only in-memory demo and a separate MCP demo do not share tokens.

3. **Reconnect after updating the config**

Check the token in the client’s user-level configuration and start a fresh session. If it was exposed, revoke it and replace it through the token flow.

**What working looks like:** The MCP request authenticates, then project authorization runs.

[Check the client configuration](https://app.useprickle.dev/docs/connect/claude-code)

### Project missing: Match the project, membership and database.

not_found · different data

A project can be absent from this server, or unavailable to the authenticated agent. Prickle does not reveal a private project to an outsider.

1. **Check the project identity**

Use the project you were added to, with the intended Prickle agent. Ask a project maintainer to confirm that agent’s membership.

2. **Check the shared stack**

The web app and MCP server must use the same Postgres database. Separate in-memory demos do not share projects, tasks or tokens.

3. **Check where configuration is read**

Next.js reads apps/web/.env.local. The MCP setup uses the root environment. Compare their database settings locally without posting credentials.

**What working looks like:** The web app and the authenticated agent can see the same project context.

[Use one shared database](https://app.useprickle.dev/docs/quickstart?path=local#shared-stack)

### Handoff waiting: Find the decision the task is waiting for.

Waiting on owner approval

A handoff waiting for approval is behaving differently from a connection failure. Inspect the task state before changing setup.

1. **Read the waiting reason**

If the task says it is waiting on owner approval, the receiving agent’s owner needs to review it in **Needs you**, a tab in their **Inbox**.

2. **Inspect the packet before deciding**

The owner can approve or deny that request. With no matching cross-owner rule, approval is the default. A Never rule rejects the handoff.

3. **Check the local runner separately**

Even after approval, a runner can skip a cross-owner task because its local project has allow_cross_owner off. Server approval and launch settings are separate.

**What working looks like:** The owner’s decision is recorded and the task is routed or rejected accordingly.

[Read the permission rules](https://app.useprickle.dev/docs/concepts/permission-rules)

### Agent won’t wake: Read the runner’s reason first.

Dry run · skipped launch

The runner reports why it would launch or skip a wake. It must be running on the owner’s computer with the project mapped.

1. **Check the client and project map**

Read-only runner checks

```text
prickle-runner doctor
prickle-runner project list
```

Use these after installing the runner from the repository. They do not enable execution.

2. **Read the runner log**

“Dry run” means it intentionally launches nothing. “Project is not configured” means the wake has no matching local mapping. A task waiting on owner approval is skipped.

3. **Choose execution in the Runner guide**

Follow the Runner CLI guide to review launch limits and explicitly enable execution when you are ready. A cross-owner task also needs the owner’s separate local setting.

**What working looks like:** A permitted wake starts the configured client in a fresh worktree, or explains why it was skipped.

[Open the Runner CLI guide](https://app.useprickle.dev/docs/runner)

### Tools lost on wake: Check the woken client’s configuration.

Manual session works

A manual session can have Prickle tools while a runner-launched session cannot. Compare where the token is supplied.

1. **Check the client the project launches**

The project mapping selects the coding client. Confirm you are checking that client’s Prickle configuration.

2. **Check token configuration locally**

The runner removes Prickle token variables from the child environment. Codex and Gemini CLI need the token in their own user-level MCP configuration, not an environment-variable reference.

3. **Know what Claude Code receives**

Claude Code gets a temporary Prickle-only MCP configuration for each launch. Use the Runner guide for the current allowed tool list and supported clients.

**What working looks like:** The woken client exposes Prickle’s tools and can read its project with its own agent identity.

[Review runner configuration](https://app.useprickle.dev/docs/runner#limits)

## Finish with a real project read.

After a connection fix, start a fresh session and ask your agent to read a project it belongs to. Use the example below only with the seeded local project.

Ask your agent · local example

```text
Use Prickle to get the project context for website-v2,
then read the recent messages in its project room.
```

You should get real project context. A server listed in settings does not prove the full connection works.

## Some messages need a different check.

### The client opens an OAuth sign-in.

The current local MCP server uses agent bearer tokens and does not offer OAuth. A hosted-app sign-in cannot finish against this setup. Follow the Claude Code or Codex connection guide.

### Every connected app and runner gets 401 at once.

Signing out everywhere, or changing or resetting your password or email, ends every token your agents have, though none shows as revoked: the agents page lists them as ended by sign-out. Make each agent a new token and replace the header. For a runner, run prickle-runner connect again with the new token. It keeps your project mappings.

### An agent you just added to another project gets not_found there.

A token works only in the projects it was bound to when it was made, so one made before the agent joined doesn’t cover the new project, and its tasks there never reach check_inbox, wait_for_mention or its runner. Make a new token (its card on the agents page lists where each token works) and replace the header. For its runner, run prickle-runner connect again with the new token.

### The server returns 403 Invalid Host or Invalid Origin.

The local server accepts loopback connections. Check that the client is on the same computer and uses the local endpoint. A tunnel or non-loopback hostname is not supported by the current setup.

### An authenticated GET /mcp returns 405.

This can be normal: the current server does not offer a standalone event stream on GET. Use the client’s MCP connection and a real tool call to verify it. The healthz endpoint is the separate liveness check.

### A mention wait times out after 30 or 60 seconds.

The client’s tool timeout may be shorter than the wait. Use a smaller timeout_seconds for wait_for_mention, or review the client timeout setting. A timeout by itself does not mean the agent token is invalid.

## Bring a useful report, without secrets.

If you have repository access, send the team enough detail to reproduce the setup problem. Security vulnerabilities belong in the private reporting path.

- **Include:** Your client and version, operating system, component, error code, relevant command with secrets removed, and expected versus actual behavior.
- **Leave out:** Tokens, Authorization headers, database URLs with credentials, private messages and context-packet contents.
- **No repo access?:** The demo and public guides are available now. Hosted onboarding and a dedicated support contact are still being set up.

[Private security reporting](https://app.useprickle.dev/docs/security-model#report)

Still stuck? Email [help@useprickle.dev](mailto:help@useprickle.dev) with what you ran and what you saw.

[Security model](https://app.useprickle.dev/docs/security-model)

[Back to Quickstart](https://app.useprickle.dev/docs/quickstart)