Common Issues & Troubleshooting

The most frequently encountered issues and their solutions, grouped by area.

Connection Issues
Authentication Problems
Memory Issues
Hook Plugin Issues
Platform-Specific Issues
Integration Problems
Billing & Plans
Getting Additional Help

Connection Issues

MCP server not connecting

Symptoms: “Failed to connect” errors, NC tools missing from your client’s tool list, timeouts.

First, confirm the server is reachable:

curl https://mcp.nexus-catalyst.com/.well-known/oauth-protected-resource
# Returns OAuth resource metadata if the server is up

Then check per client:

Claude Code: claude mcp list — if nexus-catalyst shows “needs authentication”, run /mcp in a session and complete the browser sign-in
Cursor: Agent Settings → Customize → MCPs — the server entry should show green; click the login prompt to re-authenticate if not
Claude Desktop: Customize → Connectors — check the Nexus-Catalyst connector status and re-authenticate if prompted

Common causes:

Wrong URL — it’s exactly https://mcp.nexus-catalyst.com, no trailing path
Expired OAuth session — re-authenticate from your client
Firewall/VPN blocking the connection — test the curl above from the same network

Authentication Problems

401 Unauthorized

On MCP tools (Cursor, Claude Code, Claude Desktop): your OAuth session expired. Re-authenticate from the client (Claude Code: /mcp → Authenticate; Cursor: Agent Settings → Customize → MCPs login prompt).

On the hook plugin (Claude Code): your Plugin API key is invalid or revoked.

Go to Account → API Keys in the dashboard
Generate a new Plugin key
Update NC_PLUGIN_API_KEY in your shell profile and restart your terminal

Checking for key formatting issues:

echo "[$NC_PLUGIN_API_KEY]"
# No leading/trailing spaces inside the brackets

403 Forbidden

Usually a plan or subscription-state issue:

Feature	Pro	Team
Memories	Unlimited	Unlimited
Personas	All	All
Integrations	All	All
Departments / shared memory	❌	✅

If you’re hitting Team features (departments, shared memory) on Pro, or your subscription has lapsed, head to the Billing tab.

429 Too Many Requests

You hit a rate limit. Wait a minute and retry — limits reset on a per-minute window.

Memory Issues

Memory not storing

Check the connection first — see Connection Issues. Most “not storing” reports are auth/connection failures.
Verify it landed: Dashboard → Memories → search for a keyword from the conversation.
Subscription note: if your trial ended with a failed charge or you cancelled, new writes pause while read access continues — resume from the billing page and storing works again immediately. Your existing memories are never deleted automatically.

Memory not recalling

Use specific queries:

❌ "What did we discuss?"
✅ "What database did we choose for the e-commerce project?"

Verify memories exist in the dashboard and cover the topic you’re asking about
Name the project or client in your query — recall is semantic, and project context sharpens it
Team memories are only visible on the Team plan with department sharing enabled

Irrelevant memories returned

Add project context when storing: “For the API Gateway v2 project, we decided…”
Clean up outdated memories: Dashboard → Memories → bulk select → delete
Be specific when storing — “Remember this” makes a poor memory; a decision with its reasoning makes a good one

Hook Plugin Issues (Claude Code)

Hooks not firing

nc-cc status
# ✓ Installed — UserPromptSubmit (recall) and Stop (store) hooks active
# NC_PLUGIN_API_KEY: (set)

If hooks aren’t listed, run nc-cc install again
If the key shows as missing, set NC_PLUGIN_API_KEY in your shell profile and open a new terminal

Enable debug logging and check the log:

export NC_HOOK_DEBUG=1
# then run a Claude Code session and inspect:
tail -f /tmp/nc-hook-debug.log

No `<nc-context>` block appearing

Very short prompts (under 10 characters) and short continuation replies (“yes, do that”) skip recall by design
Confirm memories exist for the topic in the dashboard
Check the workspace path isn’t disabled in dashboard project settings

Platform-Specific Issues

Claude Desktop

Connector not appearing after setup: quit Claude Desktop completely (Cmd+Q / Alt+F4) and reopen — connector changes need a full restart.

Cursor

MCP server missing from settings: confirm .cursor/mcp.json is valid JSON and in the right location (home directory for global, project root for per-project). Restart Cursor after edits.

Integration Problems

Linear

Connection failed: verify the API key in Linear Settings → API; regenerate and reconnect if revoked
Issues in the wrong team: name the team in your request, or set a default team in the dashboard Linear connection
See the Linear Integration guide for setup

GitHub

“PAT invalid”: regenerate a token with repo and read:user scopes (GitHub → Settings → Developer settings → Personal access tokens), then update it in Dashboard → Integrations

Test the token manually:

curl -H "Authorization: token YOUR_PAT" https://api.github.com/user

Slack

Notifications not sending: reinstall the incoming webhook in Slack and paste the new webhook URL in Dashboard → Integrations

Test the webhook:

curl -X POST -H 'Content-Type: application/json' \
  -d '{"text": "Test from Nexus-Catalyst"}' YOUR_WEBHOOK_URL

Billing & Plans

Upgrade not reflected

Check Dashboard → Billing for the subscription status
Log out, log back in, and hard-refresh (Ctrl+Shift+R)
If the memory limit still shows the old plan after a few minutes, contact support

What happens to my data if I cancel?

Nothing is deleted. Your account keeps read-only access for 72 hours after cancellation so you can export (Account → Data Export), and your data is retained afterwards — resubscribing restores everything. Contact support with any questions about what’s retained.

Getting Additional Help

Before contacting support

Please gather:

Platform details — which client (Claude Code, Cursor, Claude Desktop, extension), its version, and your OS
What you saw — exact error message or a screenshot
What you tried — steps from this page you’ve already attempted
Debug output if available (nc-cc status, /tmp/nc-hook-debug.log, browser console [NC] lines) — remove API keys before sharing

Contact

📧 Email: support@nexus-catalyst.com

Frequently Asked Questions

Q: Do I need an internet connection? A: Yes — memories live in your NC account, so recall and storage require connectivity.

Q: Is my data secure? A: Yes. TLS encryption in transit, AES-256 encryption at rest.

Q: How long are memories kept? A: Indefinitely on Pro and above. On Free, the oldest memory is removed when you exceed 200.

Q: Can I export my memories? A: Yes — Dashboard → Account → Data Export.

Q: Can teammates see my memories? A: Only on the Team plan with department sharing enabled. Otherwise memories are private to your account.

Back to: Documentation Home