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.

Sign-in and account

Sign-in link, browser behaviour, sign-in issues.

Symptom	Cause	Resolution
Sign-in link does not arrive	Mail in spam, provider blocks our sender, or a typo in the address.	Check your spam folder. Allow `info@knowmind.de` as a sender. If mail still does not arrive, try a different address or ask for support at `info@schuebeler-consulting.de`.
Sign-in link is expired	The link expired (valid for 24 hours) or was already used.	Request a new link at /signin.
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.

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 Cockpit under API Tokens.
HTTP 403 forbidden	Token does not have the required scope (write for create, admin for plan actions).	Create a new token with the required rights in the Cockpit and revoke the old one.
knowmind login: token rejected	Whitespace on copy or token already revoked.	Revoke the token in the Cockpit, create a new one, copy cleanly (no surrounding quotes).

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).

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'	Indexing in the background is still running or has stalled.	Wait a few minutes and reload the page. If the status does not change, write to info@knowmind.de and name the document.

Stripe, limits.

Symptom	Cause	Resolution
HTTP 402 plan_upgrade_required	The action requires a higher plan (e.g. company sign-in from Business).	The response carries `requiredPlans` with the allowed plans. Switch via Cockpit → Plan.
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.

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 Cockpit.
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.