Troubleshooting

MCP Server Won’t Connect

Symptom: POST /api/connections returns 201 but scanning shows errors for that app.

Causes & Fixes:

1. Wrong command path — Ensure the binary exists and is on $PATH inside the Docker container.

   docker exec wcp which npx   # should return /usr/local/bin/npx

2. Missing environment variables — Some MCP servers need API keys. Pass them in the env field:

   {
     "name": "notion",
     "command": "npx",
     "args": ["-y", "@anthropic/mcp-server-notion"],
     "env": { "NOTION_API_KEY": "ntn_..." }
   }

3. Server crashes on startup — Run the MCP command manually to see its stderr:

   npx -y @anthropic/mcp-server-notion 2>&1

4. npm cache issues — If npx -y downloads fail inside Docker, try pulling the image fresh or clearing the npm cache:

   docker exec wcp npm cache clean --force

---

Capabilities Scan Returns Empty

Symptom: POST /api/capabilities/scan returns {"scanned": [], "bindings_detected": 0}.

• No connections registered — call GET /api/connections first.
• If connections exist but scan is empty, the MCP servers may not expose any tools. Check the server documentation.

---

Sync Produces No Logs

Symptom: POST /api/sync/run/await returns {"synced": 0, "errors": 0, "conflicts": 0}.

• No SyncLinks exist yet. You need at least two apps with matching capabilities. Check GET /api/capabilities/syncable-pairs for valid pairs, then run a sync.
• If pairs exist but sync count is zero, the entities may already be in sync (same content_hash).

---

Conflicts Not Resolving

Symptom: POST /api/conflicts/{id}/resolve returns 409.

• The conflict was already resolved or dismissed. Query it with GET /api/conflicts?status=all to check its current status.
• Ensure the winning_app value matches one of the app names in the conflict’s sides[] array.

---

WebSocket Disconnects

Symptom: Dashboard loses real-time updates or WebSocket connections drop.

• Behind a reverse proxy (Traefik, Nginx), ensure WebSocket upgrade headers are forwarded:

  # Traefik docker label
  - "traefik.http.middlewares.wcp-headers.headers.customrequestheaders.Connection=Upgrade"

• WCP sends ping frames every 20 seconds. If your proxy has a shorter idle timeout, increase it to ≥ 30s.
• If using Cloudflare, enable WebSockets in the Network tab of your domain settings.

---

Docker Container Won’t Start

Symptom: Container exits immediately or restarts in a loop.

1. Check logs:

   docker logs wcp --tail 50

2. Port conflict — Another service is using port 8000:

   docker run -d -p 9000:8000 ...   # map to a different host port

3. Volume permissions — On some hosts the /data directory isn’t writable:

   docker exec wcp ls -la /data

4. ARM64 image on x86 — If you pulled an ARM64 image on an x86 host (or vice versa), rebuild:

   docker build --platform linux/amd64 -t wcp .

---

Database Locked Errors

Symptom: sqlite3.OperationalError: database is locked

• Only one WCP instance should write to the same SQLite file. Don’t mount the same volume into two containers.
• If the process crashed mid-write, the lock file may be stale. Restart the container:

  docker restart wcp

---

CORS Errors in Dashboard

Symptom: Browser console shows Access-Control-Allow-Origin errors.

• Set the WCP_CORS_ORIGINS environment variable to your dashboard URL:

  -e WCP_CORS_ORIGINS=https://dashboard.example.com

• For local development, use * (wildcard). Never use * in production.

---

Common HTTP Error Codes

Code	Meaning	What to do
404	Resource not found	Check the connection name, conflict ID, or wcp_id
409	Conflict / duplicate	Resource already exists or conflict already resolved
422	Validation error	Check request body — missing or invalid fields
500	Internal server error	Check docker logs wcp for the traceback

---

Getting Help

• GitHub Issues: github.com/lucasmella-stack/WCP/issues
• Logs: Always include output from docker logs wcp --tail 100 and GET /api/sync/status