Skip to main content

FAQ & Troubleshooting

"MCP fails with network error talking to https://api.clone.is/...: fetch failed"​

The MCP server can connect to itself but not to the upstream Django API. Three usual causes, in order of likelihood:

  1. DNS NXDOMAIN cached on your local resolver. Even after the registrar's A record is correct and dig @8.8.8.8 api.clone.is returns the right IP, your ISP's resolver may still have the negative cache. Wait the SOA TTL out (≤ 1 hour for Namecheap) or pin the host in /etc/hosts. See DNS & TLS.
  2. Wrong CLONE_API_URL. apps/mcp/src/index.ts defaults to https://api.clone.is. Override via the env variable when running locally (CLONE_API_URL=http://localhost:8001).
  3. Server is down. curl -sS -X POST $CLONE_API_URL/api/recording/events/ should at least return a 401, not a connection error.

"Recording helpers return is not valid under any of the given schemas"​

The most common cause is a source value that isn't in the enum. source must be one of desktop, cli, mobile, smartglass, agent, integration. Free-form values like "claude-code" belong in source_detail, not source. The record_agent_prompt / record_agent_response / start_session / stop_session helpers all share the same enum.

The other gotchas:

  • record_agent_prompt takes prompt, not text.
  • record_agent_response takes response, not text.
  • integration events require source_detail (the upstream provider name).

See Schema for the full validation rules.

"Predictions return 504 Gateway Time-out under load"​

/api/predictions/predict/ performs a real Anthropic call (3–6 seconds is typical). Many concurrent calls queue behind nginx's proxy_read_timeout and individual requests can hit it. Mitigations:

  • Issue calls serially, or in batches of ≤ 4 concurrent requests.
  • Use the batch endpoint (POST /api/predictions/predict/batch/) — it shares one Memory bundle across up to 100 prompts.
  • Tune nginx: increase proxy_read_timeout for /api/predictions/ if your traffic pattern is consistently slow upstream.

"All my predictions come back with confidence around 0.4 and status: escalated"​

You're cold-start. The Memory layer hasn't seen enough of your real history yet. Two ways to seed it:

  1. Push real events through record_agent_prompt / record_agent_response — actual question/answer pairs from how you really work.
  2. Run promotion: POST /api/memory/promote/episodes/ then POST /api/memory/promote/facts/ (LLM-driven, costs Anthropic tokens).

Calibration improves once POST /api/memory/context/ returns a non-empty bundle.

"I edited the prediction. How do I tell Clone?"​

POST /api/predictions/<id>/feedback/ with status: "edited" and the actual reply. The Prediction layer uses these to compute precision in /predictions/stats/ ((auto + accepted) / answered).

"My apps/web build fails with Cannot find module '@clone/design'"​

The Vite alias @clone/design resolves to ../../packages/design. From a fresh clone, make sure the symlinks under apps/web/public/ are intact (they point into packages/design/assets/). The apps/web/Dockerfile mirrors that layout in the build container; if you're building outside Docker, do git config core.symlinks true on Windows checkouts.

"How do I reset my Memory layer for testing?"​

There's no public "wipe all memory" endpoint by design — accidental resets are catastrophic. Either:

  • Delete rows by ID via the per-tier DELETE /api/memory/{raw,episodes,facts}/<uuid>/ endpoints.
  • Or, in development, run manage.py shell and use the ORM directly.

"Where do I file a bug?"​

Open an issue or PR at github.com/cloneisyou/clone. PR template lives at .github/PULL_REQUEST_TEMPLATE.md; issues are free-form.