Troubleshooting

Your MCP client is pointing at a project slug that doesn't exist (or your API key doesn't have access).

# Re-run setup (recommended)
npx veriova-mcp@latest setup

# Or diagnose
npx veriova-mcp@latest doctor

You're calling an authenticated endpoint without a Bearer key.

curl -H "Authorization: Bearer cv_..." https://api.veriova.com/api/v1/projects

Either include the project slug/param, or set a default project for your API key once:

curl -X POST \
  -H "Authorization: Bearer cv_..." \
  -H "Content-Type: application/json" \
  -d '{"project_slug":"my-app"}' \
  https://api.veriova.com/api/v1/me/default-project

You've hit your daily API call limit. Check your current usage via the response headers:

curl -v -H "Authorization: Bearer cv_..." \
  https://api.veriova.com/api/v1/projects 2>&1 | grep X-RateLimit

# X-RateLimit-Limit: 500
# X-RateLimit-Remaining: 0

Free tier: 500 calls/day. Pro: 10,000. Team: 100,000. Limits reset at midnight UTC. Upgrade at veriova.com/pricing.

If you're calling the API directly from browser JavaScript and see CORS errors, the origin must be in the server's allowlist. By default, only https://veriova.com and localhost:3000 are allowed.

Self-hosted? Set the CORS_ALLOW_ORIGINS environment variable on your backend to a comma-separated list of allowed origins:

CORS_ALLOW_ORIGINS=https://yourdomain.com,http://localhost:3000

Using the hosted API from a custom frontend? Use the SDKs or MCP server instead of direct browser calls. The API is designed for server-to-server and CLI/MCP usage, not browser-side fetch.

If /context-pack returns an empty pack despite having memories, check these in order:

1. Memory status-Only VERIFIED and PINNED items are included. Candidates are excluded unless you pass include_candidates: true.
2. Project slug mismatch-Make sure the project_slug in your request matches the project your memories are stored in.
3. Query too specific-The search cascades: semantic (embeddings) -†- keyword (full-text) -†- broad (ILIKE). If you have no OpenAI key configured, only keyword and broad search are available. Try a simpler query.

curl -H "Authorization: Bearer cv_..." \
  "https://api.veriova.com/api/v1/memory?project=my-project&status=VERIFIED"

If semantic search isn't working, check whether the OpenAI API key is configured on your backend:

curl https://api.veriova.com/api/v1/health | jq .embedding_service

If embedding_service shows unavailable, the OPENAI_API_KEY environment variable is missing or invalid. Without it, veriova falls back to PostgreSQL full-text search, which still works but is less accurate.

If you're self-hosting and don't want to use OpenAI, keyword search is fully functional without embeddings.

If connecting via Claude Chat or another remote MCP client fails during OAuth:

1. Callback URL mismatch-The OAuth flow uses dynamic client registration. Make sure your MCP client supports the POST /oauth/register endpoint for PKCE flow.
2. Session cookie scope-The login session cookie is set on .veriova.com, so it works across veriova.com and api.veriova.com. If you're self-hosting on a different domain, ensure the cookie domain matches.
3. Check the discovery endpoint:

curl https://api.veriova.com/.well-known/oauth-authorization-server | jq .

Check Mailgun settings on the server (domain, API key, from address) and Mailgun logs for bounces. Also verify the email isn't in your spam folder.

If the website loads inconsistently, your local DNS cache may be stale. On macOS:

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder