Troubleshooting

This guide covers common problems and their solutions. Check your issue below.

MCP Connection Issues

MCP server fails to start

Symptom: Error: Cannot find module or MCP tools unavailable in Claude Code

Solutions:

1. Verify Node.js is installed:

node --version  # Should be 22+

2. Check the script path is absolute (not relative):

# ❌ Bad: "args": ["./preqstation-mcp-server.mjs"]
# ✅ Good: "args": ["/Users/kendrick/projects/preqstation-skill/scripts/preqstation-mcp-server.mjs"]

3. Verify the script file exists:

ls -la /path/to/preqstation-skill/scripts/preqstation-mcp-server.mjs

4. Check environment variables are set:

echo $PREQSTATION_API_URL
echo $PREQSTATION_TOKEN

5. Restart Claude Code or re-add the MCP server:

claude mcp remove preqstation
claude mcp add -s user \
  --env='PREQSTATION_API_URL=https://...' \
  --env='PREQSTATION_TOKEN=preq_...' \
  preqstation -- node /path/to/preqstation-mcp-server.mjs

Tools appear in MCP but return errors

Symptom: preq_list_tasks or other tools fail with 401 Unauthorized

1. Verify token format (should start with preq_):

echo $PREQSTATION_TOKEN  # Should output: preq_xxxxxxxxx

2. Verify token is not expired:

• Go to projects-manager UI → Settings → API Keys
• Check token creation date and expiration
• Generate a new token if needed

3. Test connectivity directly:

curl -H "Authorization: Bearer $PREQSTATION_TOKEN" \
  "$PREQSTATION_API_URL/api/health"
# Should return: {"status":"ok"}

4. Verify API URL is correct (must include protocol):

# ❌ Bad: "preqstation-lp.vercel.app"
# ✅ Good: "https://preqstation-lp.vercel.app"

Token & Authentication Issues

”Invalid token” error on every MCP call

Symptom: Token auth fails even with correct-looking token

Cause: Expired Token

Check: In projects-manager UI, go to Settings → API Keys and check expiration date.

Fix: Generate a new token:

1. Click “New Token”
2. Copy the new token value
3. Update PREQSTATION_TOKEN environment variable
4. Re-register MCP server with new token

Cause: Token Revoked

Check: List tokens in Settings → API Keys to see if token is still there.

Fix: Generate a fresh token (old one may have been revoked).

Cause: Wrong Bearer Format

Check: Environment variable and MCP config have exact token value.

Problem: Token was pasted with extra spaces or quotes.

Fix:

# ❌ Bad:
export PREQSTATION_TOKEN=" preq_xxxxx " # spaces!

# ✅ Good:
export PREQSTATION_TOKEN="preq_xxxxx"   # no extra spaces

Worktree & Git Issues

Worktree conflicts or cleanup failures

Symptom: fatal: invalid reference: <branch> or stale worktree directory

Solutions:

1. List existing worktrees:

git -C <project_cwd> worktree list

2. Remove stale worktrees:

git -C <project_cwd> worktree remove <path> --force
git -C <project_cwd> worktree prune

3. If worktree is locked:

git -C <project_cwd> worktree unlock <path>
git -C <project_cwd> worktree remove <path> --force

4. Check for corrupted .git/worktrees/ directory:

ls -la <project_cwd>/.git/worktrees/
# If corrupted, delete the lock file:
rm <project_cwd>/.git/worktrees/<worktree_name>/locked

Remote push verification fails

Symptom: failed: ... - Remote push verification failed

Issue: Branch not pushed

Cause: deploy_commit_on_review=true requires successful push before completing task.

Check:

git -C <project_cwd> branch -r | grep <branch_name>
# Or:
git ls-remote --heads origin <branch_name>

Fix:

1. Manually push the branch:

git -C <project_cwd> push origin <branch_name>

2. Then call preq_complete_task again

Issue: Wrong branch name

Cause: Branch created locally but with different name.

Check: Compare local vs. resolved branch name:

git -C <project_cwd> branch
# Expected: preqstation/PROJ/feature-name

Fix: Push with correct name or use preq_complete_task with branchName parameter.

Build & Compilation Errors

”npm install” fails in worktree

Symptom: npm ERR! 404 Not Found or dependency resolution errors

Cause: Wrong package manager

Check: Use the package manager already configured by the repo.

Fix: Do not delete lockfiles as a first step. Run the repo’s intended install command instead:

# examples
pnpm install
npm install
yarn install

Cause: Node version mismatch

Check:

node --version
cat <cwd>/.nvmrc  # If using nvm

Fix: Use correct Node version:

nvm use  # If .nvmrc exists
node --version  # Should match project requirements

Cause: Private dependencies

Check: .npmrc credentials or package.json scoped packages.

Fix:

# Ensure .npmrc has auth token for private registry:
echo "@scope:registry=https://npm.example.com" >> ~/.npmrc
echo "//npm.example.com/:_authToken=YOUR_TOKEN" >> ~/.npmrc

Project Mapping Issues

”Project path not found”

Symptom: OpenClaw asks for a project path even though you thought it was already configured.

Solutions:

1. Confirm the mapping exists in OpenClaw agent memory.

2. If you use the sample MEMORY.md format as a reference, check that the row looks like:

| key | cwd | note |
|-----|-----|------|
| proj | /absolute/path | Description |

3. Verify the project key matches the task prefix:

• PRJ-284 should normally map to prj

4. Ensure paths are absolute (not relative):

./projects/example

# ✅ Good: /Users/kendrick/projects/example

OpenClaw Execution Issues

Session never completes or seems stuck

Symptom: Process shows no output for hours, or stuck at same log line

Solutions:

1. Check session status:

process action:poll sessionId:<id>

2. Read last 100 lines of output:

process action:log sessionId:<id> | tail -100

3. If truly stuck, kill the session:

process action:kill sessionId:<id>

4. Check for infinite loops or blocking I/O:

# Common causes:
# - npm install hung on network
# - Interactive prompts waiting for input
# - Subprocess blocking on child process

“Permission denied” when accessing project files

Symptom: Error: EACCES: permission denied in worktree

Solutions:

1. Verify directory permissions:

ls -ld <project_cwd>
# Should be readable/writable by current user

2. Check worktree permissions:

ls -ld <cwd>
chmod -R u+rw <cwd>  # If needed

3. Ensure Git can write to worktree:

touch <cwd>/.test-write
rm <cwd>/.test-write

Common Mistakes

❌ Forgetting to update OpenClaw project mappings

Issue: OpenClaw can’t resolve project path, requires manual input each time.

Fix: Update the OpenClaw mapping whenever you clone a new project or change paths. If you keep a reference MEMORY.md, keep that in sync too:

| key | cwd | note |
|-----|-----|------|
| newproj | /absolute/path | Added 2026-03-06 |

❌ Using relative paths in project mappings

Issue: Worktree creation fails because path doesn’t expand.

Fix: Always use absolute paths:

# Get absolute path:
pwd  # from within the project

❌ Not cleaning up old worktrees

Issue: Disk fills up, performance degrades.

Fix: Periodic cleanup:

git -C <project_cwd> worktree list
git -C <project_cwd> worktree remove <old_path> --force
git -C <project_cwd> worktree prune

❌ Expecting PREQ tools without MCP

Issue: preq_* tools are unavailable because the MCP server was never registered.

Fix: Ensure the PREQSTATION MCP server is registered:

claude mcp list | grep preqstation

Getting Help

If you’ve checked all above:

1. Gather diagnostics:

   echo "API URL: $PREQSTATION_API_URL"
   echo "Token format: ${PREQSTATION_TOKEN:0:4}... (masked)"
   node --version
   git --version
   npm --version

2. Test basic connectivity:

   curl -H "Authorization: Bearer $PREQSTATION_TOKEN" \
     "$PREQSTATION_API_URL/api/health" | jq .

3. Check logs:

   • Claude Code: Settings → Logs
   • OpenClaw: Session output via process action:log
   • projects-manager: Vercel dashboard logs

4. File an issue with:

   • System info (OS, Node version)
   • Error message (full stack trace)
   • Steps to reproduce
   • Diagnostics output (without exposing tokens)