Service

Fehlerbehebung

Gegliedert nach Bereichen. Wenn die Auflösung nicht passt, beschreiben Sie das Symptom (mit Zeitstempel und Tenant-Slug) per E-Mail an info@schuebeler-consulting.de — wir antworten innerhalb eines Werktags.

Anmeldung und Konto

Magic-Link, Browser-Verhalten, Login-Probleme.

Symptom	Ursache	Auflösung
Anmelde-Link kommt nicht an	Mail im Spam, Provider blockiert unseren Absender oder Tippfehler in der Adresse.	Spam-Ordner prüfen. `info@schuebeler-consulting.de` als Absender zulassen. Wenn weiterhin nichts kommt, eine andere Mail-Adresse probieren oder über `info@schuebeler-consulting.de` Support anfragen.
Magic-Link ist abgelaufen	Link ist abgelaufen (24 Stunden gültig) oder wurde bereits benutzt.	Neu anfordern über /signin und sofort nach Erhalt klicken.
Nach Login Weiterleitung-Schleife	Drittanbieter-Cookies geblockt oder Browser-Erweiterung blockiert Cookies für knowmind.de.	Cookies für knowmind.de zulassen, gegebenenfalls Inkognito-Fenster verwenden.

API-Tokens und Anmeldung von Werkzeugen

401, 403, abgewiesene Tokens.

Symptom	Ursache	Auflösung
HTTP 401 unauthorized	Token fehlt, ist widerrufen oder Tippfehler im Authorization-Header.	Format prüfen: `Authorization: Bearer kmt_…` mit Leerzeichen zwischen Bearer und Token. Token im Dashboard unter API-Tokens erneut prüfen.
HTTP 403 forbidden	Token hat den Scope nicht (write für Anlage, admin für Tarif-Aktionen).	Im Dashboard den Token bearbeiten und Scope ergänzen, oder einen neuen Token mit den nötigen Scopes erstellen.
knowmind login: token wird abgelehnt	Whitespace beim Kopieren oder Token bereits widerrufen.	Token im Dashboard widerrufen, neuen erstellen, sauber kopieren (ohne umschließende Anführungszeichen).

MCP- und Connector-Anbindung

Werkzeuge tauchen nicht auf, Tool-Aufrufe brechen ab.

Symptom	Ursache	Auflösung
claude mcp list zeigt knowmind als „Failed"	knowmind-CLI nicht im PATH oder fehlerhafter Token-Header in der HTTP-Variante.	Variante A: `which knowmind` / `where knowmind` ausführen — CLI gegebenenfalls neu installieren. Variante B: Token-Wert im Header prüfen.
Claude Desktop zeigt knowmind-Werkzeuge nicht	Claude Desktop nicht vollständig neu gestartet.	Über das Menüleisten- oder Taskleisten-Symbol „Beenden" wählen, dann neu starten.
Tool-Aufruf bricht mit Timeout ab	Erste Anfrage nach Cold-Start oder kurzes Netzwerk-Problem.	Anfrage wiederholen. Bei dauerhaft: mit `knowmind health` die Erreichbarkeit prüfen.
OAuth-Anbindung scheitert mit „Token-Endpunkt nicht erreichbar"	Netzwerk-Sperre auf knowmind.de oder Popup-Blocker.	Popup-Blocker für knowmind.de und die Connector-Seite (claude.ai bzw. chatgpt.com) deaktivieren.

Recall und Suche

Leere Trefferliste, schlechte Treffer, Indexierung hängt.

Symptom	Ursache	Auflösung
knowmind_recall liefert leere Liste	Korpus leer, Token gehört zum falschen Arbeitsbereich, oder Frage außerhalb des Themas.	`knowmind stats` ausführen — wenn 0 Erinnerungen, neuen Inhalt anlegen. Wenn richtige Anzahl: Frage mit konkreteren Begriffen testen.
Treffer thematisch verwandt, aber faktisch falsch	Vektor-Stage zieht semantisch ähnliche Inhalte hoch, BM25-Stage findet keinen wortwörtlichen Treffer.	Frage mit präzisem Schlagwort wiederholen oder über knowmind_update_fact die korrekte Aussage als gültig markieren.
Dokument-Status bleibt auf „Indexiert"	Embedding-Schritt hängt — bei BYOK-Setup oft fehlender oder ungültiger Anbieter-Schlüssel.	Dashboard → BYOK-Schlüssel prüfen. Bei knowmind-Default-Embedding einige Minuten warten und neu laden.

Tarif, Budget und Rechnung

Stripe, Limits, Warnmails.

Symptom	Ursache	Auflösung
HTTP 402 plan_upgrade_required	Aktion erfordert einen höheren Tarif (z. B. Webhooks ab Team).	Antwort enthält `requiredPlans` mit zulässigen Tarifen. Über Dashboard → Tarif wechseln.
Budget-Warnmail kommt nicht	Mail im Spam, Empfänger-Adresse blockiert unseren Absender, oder Tippfehler.	Spam-Ordner prüfen, Empfänger im Cockpit korrigieren, gegebenenfalls eine alternative Adresse hinterlegen.
Stripe-Portal lädt nicht	Browser blockiert Drittanbieter-Cookies oder Stripe vorübergehend nicht erreichbar.	Cookies für stripe.com zulassen. Bei dauerhaftem Problem den Stripe-Status auf status.stripe.com prüfen.

Webhooks

Lieferungen schlagen fehl, Signatur stimmt nicht.

Symptom	Ursache	Auflösung
Webhook wird als „dead" markiert	Endpunkt liefert keine 2xx innerhalb 15 Sekunden, mehrere Retries scheitern.	Endpunkt-Logs prüfen. Sofort 200 zurückgeben, Verarbeitung in eine Queue verschieben.
Subscription deaktiviert	20 aufeinanderfolgende Fehler bei Lieferung.	Ursache am Endpunkt beheben, im Dashboard die Subscription manuell reaktivieren.
Signatur-Prüfung schlägt fehl	Framework hat den Roh-Body verändert (Trimming, Re-Serialisierung).	Im Handler den unverarbeiteten Body (String/Bytes) verwenden, nicht das geparste JSON.