Skip to content

Troubleshooting

Solutions for common issues organized by category.

Connection Issues

"Unable to connect to MCP server"

Cause: The server URL is wrong or the service is temporarily unavailable.

Solution:

  1. Verify the service is running: visit https://syncontext.dev/health in your browser -- it should return {"status":"ok"}
  2. Check the URL is exactly https://syncontext.dev/mcp (with https, not http)
  3. If using a query parameter key: https://syncontext.dev/mcp?key=YOUR_KEY -- ensure no extra spaces

"Connection timeout"

Cause: Network issues or Cloudflare bot protection blocking the connection.

Solution:

  1. Try again after 30 seconds
  2. If using a VPN, try without it
  3. Verify your internet connection can reach syncontext.dev

"SSL/TLS errors"

Cause: Using http:// instead of https://.

Solution: Always use https://syncontext.dev/mcp -- the service requires HTTPS.

Authentication Issues

"Invalid or missing API key"

Cause: The API key is incorrect, expired, or missing from the request.

Solution:

  1. Log into the dashboard and check Settings
  2. If you've regenerated your key, update it in all your AI clients
  3. Ensure there are no leading/trailing spaces in the key
  4. For ChatGPT: key goes in the URL as ?key=YOUR_KEY
  5. For Claude Desktop: key goes in the --header argument

"401 Unauthorized"

Cause: The API key or session token is not valid.

Solution:

  1. Regenerate your API key in Settings and update all connections
  2. If using the dashboard, log out and log back in (session tokens expire after 24 hours)
  3. If you recently rotated your API key, all previous sessions were invalidated -- log in again
  4. Verify the key is sent correctly:
    • MCP via header: X-API-Key: YOUR_KEY
    • MCP via query param: https://syncontext.dev/mcp?key=YOUR_KEY
    • REST API: Authorization: Bearer YOUR_KEY or X-API-Key: YOUR_KEY

"Please verify your email before logging in"

Cause: You registered but haven't clicked the verification link in your email.

Solution:

  1. Check your inbox (including spam/junk) for an email from [email protected]
  2. Click the verification link in the email (valid for 24 hours)
  3. If you can't find it, go to the login page and click "Resend verification email" (rate limited to 3 per hour)
  4. After clicking the link, you'll be redirected to the login page with a success banner

Note: Your API key works immediately for MCP clients (Claude, ChatGPT). Only dashboard login requires email verification.

"Verification email not received"

Solution:

  1. Check your spam/junk folder — emails are sent from [email protected]
  2. Use the "Resend verification email" button on the login page
  3. Wait a few minutes — email delivery can take up to 5 minutes
  4. If still not received after multiple resends, try registering with a different email address

"403 Forbidden" / "Account suspended"

Cause: Your account has been suspended by an administrator.

Solution: Contact support for assistance.

"429 Too Many Requests"

Cause: You have exceeded your rate limit.

Rate limits by tier:

Endpoint Type Free Pro Team
Auth endpoints (login, register) 5/min per IP 5/min per IP 5/min per IP
API endpoints 30/min 120/min 300/min

Solution:

  1. Check the Retry-After header in the response for how many seconds to wait
  2. Reduce the frequency of your requests
  3. If you consistently hit limits, upgrade your plan in the dashboard under Billing
  4. For automated workflows, add delays between API calls

MCP Client Issues

ChatGPT: Tools don't appear

Solution:

  1. Go to Settings > Apps and verify SynContext is listed
  2. Disconnect and reconnect the app
  3. Start a new conversation -- tools are not available in existing chats
  4. Verify you have ChatGPT Plus, Team, or Enterprise (free tier doesn't support MCP)

ChatGPT: New tools missing after SynContext update

Cause: ChatGPT caches the tool list at the moment you first connect. If SynContext adds new tools after your initial connection (for example, the GitHub integration tools added in v0.6.0), ChatGPT will not see them until you reconnect.

This is a known limitation of ChatGPT's MCP client, not a SynContext bug. The MCP protocol defines a notifications/tools/list_changed mechanism for servers to notify clients of tool changes, but ChatGPT does not currently respond to this notification.

Solution:

  1. Go to Settings > Apps
  2. Find SynContext and disconnect it
  3. Reconnect with your MCP Server URL: https://syncontext.dev/mcp?key=YOUR_KEY
  4. Open a new conversation and verify the new tools appear
  5. You can ask ChatGPT: "List all SynContext tools you can see" to confirm

Tip: This only needs to be done when SynContext releases new tools. Check our changelog for release notes mentioning new MCP tools.

Claude Desktop: New tools missing after SynContext update

Cause: Same caching behavior as ChatGPT -- Claude Desktop reads the tool list once at startup.

Solution: Restart Claude Desktop. It will re-discover all available tools on the next connection.

Claude Code: New tools missing after SynContext update

Solution:

  1. Remove the connection: claude mcp remove syncontext
  2. Re-add it: claude mcp add syncontext --transport http https://syncontext.dev/mcp --header "X-API-Key: YOUR_KEY"
  3. Verify: claude mcp list should show all current tools

ChatGPT: Asks to confirm every tool call

This is expected behavior. ChatGPT requires user confirmation for all external tool calls. Click "Confirm" or "Allow" to proceed.

ChatGPT: Deep Research doesn't find my context

Solution:

  1. Verify search works directly: ask ChatGPT to Search my SynContext for [keyword]
  2. If search works but Deep Research doesn't use it, rephrase your query to be more specific
  3. Ensure you have context entries stored (check in the dashboard)

Claude Desktop: Tools don't appear

Solution:

  1. Open claude_desktop_config.json and verify the JSON syntax (use a JSON validator)
  2. Common mistakes: missing commas, wrong brackets, trailing comma after last item
  3. Restart Claude Desktop after any config change -- it only reads the file on startup
  4. Check that you see the hammer icon in the chat input area

Claude Desktop: "npx not found"

Cause: Node.js is not installed or not in your system PATH.

Solution:

  1. Install Node.js from nodejs.org (LTS version recommended)
  2. Restart your terminal after installing
  3. Verify: run npx --version -- it should print a version number

Claude Code: "transport error"

Solution:

  1. Verify the command used: claude mcp add syncontext --transport http https://syncontext.dev/mcp --header "X-API-Key: YOUR_KEY"
  2. Run claude mcp list to check if syncontext is registered
  3. Remove and re-add: claude mcp remove syncontext then add again

Dashboard Issues

Can't log in

Solution:

  1. Check email verification — if you see "Please verify your email", check your inbox and click the verification link first
  2. Verify your email and password are correct
  3. Clear browser cookies/cache for syncontext.dev
  4. Try an incognito/private window
  5. If you are rate-limited (5 failed attempts in 1 minute), wait 60 seconds and try again
  6. If you forgot your password, use the password reset flow (see below)

Password Reset

If you forgot your dashboard password:

  1. Go to https://syncontext.dev/app and click "Forgot password?"
  2. Enter the email address associated with your account
  3. Check your inbox for a password reset email from [email protected]
  4. Click the reset link in the email (valid for 1 hour)
  5. Set a new password

If you don't receive the email:

  • Check your spam/junk folder
  • Verify you are using the correct email address
  • The reset email is sent even if the account doesn't exist (to prevent email enumeration), so absence of an email may mean the address is wrong

Data doesn't appear or is outdated

Solution:

  1. Refresh the page (Ctrl+R / Cmd+R)
  2. Session tokens expire after 24 hours -- log out and log back in
  3. Check if you're looking at the correct project
  4. If you recently created entries via MCP, they should appear immediately -- try a hard refresh (Ctrl+Shift+R / Cmd+Shift+R)

API Errors

"413 Content Too Large"

Cause: The request body exceeds the 500 KB size limit.

Solution:

  1. Reduce the size of the content you are sending
  2. Split large entries into multiple smaller ones
  3. For bulk imports, send entries one at a time rather than all at once
  4. If you are sending base64-encoded data, note that encoding increases size by approximately 33%

"422 Unprocessable Entity"

Cause: The request body is valid JSON but contains invalid field values.

Solution:

  1. Check that required fields are present and non-empty
  2. Verify field types match the API specification (strings, integers, etc.)
  3. Ensure enum values (like search mode) use allowed values

Webhook Issues

Webhooks not being delivered

Solution:

  1. Verify the webhook URL is correct and publicly accessible
  2. Private/internal URLs are blocked by SSRF protection (localhost, 10.x.x.x, 172.16.x.x, 192.168.x.x)
  3. Only http and https schemes are supported
  4. Check the webhook delivery log in the dashboard for error details
  5. Ensure your receiving server responds with a 2xx status code within 10 seconds

Webhook payloads are empty or malformed

Solution:

  1. Webhooks are delivered as POST requests with a JSON body
  2. Ensure your endpoint parses the Content-Type: application/json body
  3. Check the delivery log for the exact payload that was sent

Quota and Billing Issues

"Quota exceeded" or "limit reached"

Cause: You've reached the limit for your current plan.

Solution:

  1. Check your usage in the dashboard > Analytics
  2. Upgrade your plan in Billing
  3. Delete unused projects or entries to free up space

Current limits:

Resource Free Pro Team
Projects 3 50 Unlimited
Entries 100 5,000 Unlimited
Decisions 50 2,000 Unlimited

Payment failed

Solution:

  1. Go to Billing in the dashboard
  2. Click "Manage Subscription" to open the Stripe portal
  3. Update your payment method
  4. The warning will clear automatically after a successful payment

See Billing for more details.

Feature Access Issues

"This feature requires a Pro or Team subscription"

Cause: You're on the free tier trying to use a paid feature.

Gated features:

  • Semantic search (mode=semantic)
  • Hybrid search (mode=hybrid)
  • Webhooks (create)
  • Audit log

Solution: Upgrade your plan in the dashboard under Billing. Keyword search and all other features are available on the free tier.

Data Issues

"Entry not found"

Cause: The entry ID doesn't exist or belongs to a different account.

Solution:

  1. Verify the entry ID is correct
  2. Each user's data is isolated -- you can only access your own entries
  3. The entry may have been deleted

Search returns no results

Solution:

  1. Try different keywords -- full-text search matches against titles and tags
  2. Try semantic or hybrid search mode: ask your AI to Search SynContext for "topic" using hybrid mode
  3. Verify you have entries stored by listing your projects first
  4. Content is searched via TF-IDF semantic search (not FTS5), so content matches require semantic or hybrid mode

Content appears empty or shows "[ENCRYPTED]"

Cause: Content is encrypted at rest and requires the server's encryption key to decrypt.

Solution: This is normal server behavior. Content is automatically decrypted when you access it through the API or dashboard. If you see "[ENCRYPTED]", the server's encryption key may have changed -- contact support.

Still Need Help?

If your issue isn't covered here, check: