Service
Troubleshooting
Grouped by area. If the resolution does not match, describe the symptom (with timestamp and tenant slug) by email to info@schuebeler-consulting.de — we answer within one working day.
Sign-in and account
Magic link, browser behaviour, login issues.
| Symptom | Cause | Resolution |
|---|---|---|
| Sign-in link does not arrive | Mail in spam, provider blocks Brevo, or a typo in the address. | Check your spam folder. Allow info@schuebeler-consulting.de as a sender. If mail still does not arrive, try a different address or ask for support at info@schuebeler-consulting.de. |
| Magic link is expired | The link is valid for only 15 minutes. | Request a new link at /signin and click it immediately. |
| Redirect loop after sign-in | Third-party cookies blocked, or a browser extension blocks knowmind.de cookies. | Allow cookies for knowmind.de, or use a private window. |
API tokens and tool sign-in
401, 403, rejected tokens.
| Symptom | Cause | Resolution |
|---|---|---|
| HTTP 401 unauthorized | Token missing, revoked, or typo in the Authorization header. | Check the format: Authorization: Bearer kmt_… with a space between Bearer and the token. Verify the token in the dashboard under API Tokens. |
| HTTP 403 forbidden | Token does not have the required scope (write for create, admin for plan actions). | Edit the token in the dashboard and add the scope, or create a new token with the required scopes. |
| knowmind login: token rejected | Whitespace on copy or token already revoked. | Revoke the token in the dashboard, create a new one, copy cleanly (no surrounding quotes). |
MCP and connector integration
Tools do not appear, tool calls fail.
| Symptom | Cause | Resolution |
|---|---|---|
| claude mcp list shows knowmind as 'Failed' | knowmind CLI not on PATH, or bad header token in the HTTP option. | Option A: run which knowmind / where knowmind — reinstall the CLI if missing. Option B: verify the token value in the header. |
| Claude Desktop does not show the knowmind tools | Claude Desktop was not fully restarted. | From the menu-bar or task-bar icon choose "Quit", then start the app again. |
| Tool call ends with a timeout | First request after cold start or a brief network issue. | Retry. If persistent, run knowmind health to verify reachability. |
| OAuth integration fails with 'token endpoint unreachable' | Network block on knowmind.de or popup blocker. | Disable the popup blocker for knowmind.de and the connector site (claude.ai / chatgpt.com). |
Recall and search
Empty hit list, weak hits, indexing stuck.
| Symptom | Cause | Resolution |
|---|---|---|
| knowmind.recall returns an empty list | Corpus empty, token belongs to the wrong workspace, or the question is outside the topic. | Run knowmind stats — if 0 memories, add new content. If the count is right, try the question with more specific terms. |
| Hits are topically related but factually wrong | The vector stage surfaces semantically similar content; the BM25 stage finds no literal match. | Retry the question with a precise keyword, or mark the correct statement as valid via knowmind.update_fact. |
| Document status stays on 'Indexed' | Embedding step stuck — with BYOK setups, often a missing or invalid provider key. | Check Dashboard → BYOK Keys. With the default embedding, wait a few minutes and reload. |
Plan, budget and billing
Stripe, limits, warning emails.
| Symptom | Cause | Resolution |
|---|---|---|
| HTTP 402 plan_upgrade_required | The action requires a higher plan (e.g. webhooks from Business API). | The response carries requiredPlans with the allowed plans. Switch via Dashboard → Plan. |
| Budget warning email does not arrive | Mail in spam, recipient blocks Brevo, or typo in the address. | Check the spam folder, correct the recipient in the cockpit, optionally use a different address. |
| Stripe portal does not load | Browser blocks third-party cookies, or Stripe is temporarily unreachable. | Allow cookies for stripe.com. If the issue persists, check status.stripe.com. |
Webhooks
Deliveries fail, signatures mismatch.
| Symptom | Cause | Resolution |
|---|---|---|
| Webhook marked 'dead' | Endpoint does not return 2xx within 15 seconds; multiple retries fail. | Check endpoint logs. Return 2xx immediately and push work into a queue. |
| Subscription disabled | 20 consecutive delivery failures. | Fix the endpoint, then reactivate the subscription manually in the dashboard. |
| Signature verification fails | Framework altered the raw body (trim, re-serialisation). | Use the unmodified raw body (string or bytes) in the handler, not the parsed JSON. |