Zum Hauptinhalt springen

Troubleshooting

Häufige Fehlermodi und wie man sie behebt. Die MCP-(Model Context Protocol)-Services werfen niemals aus einem Tool heraus – jedes Problem kommt als IsSuccess: false plus einer ErrorMessage zurück. Lesen Sie zuerst die Meldung; die Tabelle unten ordnet die typischen Meldungen den Grundursachen zu.

Verbindung & Registrierung​

claude mcp list zeigt den Server, aber mit einem Verbindungsfehler​

Die Server-URL ist erreichbar, aber der MCP-Handshake ist fehlgeschlagen.

  • Falscher Pfad – die URL muss auf /mcp (ohne Tenant) oder /{tenantId}/mcp enden. Nur der Host ohne Pfad gibt 404 zurück.
  • Netzwerkerreichbarkeit – für die Produktionsendpunkte müssen Sie möglicherweise im Firmen-VPN sein. Prüfen Sie mit curl -sSI <url> – eine 200/405-Antwort ist in Ordnung; ein Timeout bedeutet Netzwerk, nicht MCP.

mcp__octomesh__*-Tools erscheinen nach der Registrierung nicht​

Claude Code zählt Tools nur beim Sitzungsstart auf.

  1. Bestätigen Sie mit claude mcp list, dass der Server Connected anzeigt.
  2. Starten Sie Ihre Claude-Code-Sitzung neu (/exit, dann eine neue im selben Projekt starten).
  3. Der Tool-Katalog sollte nun sichtbar sein – bitten Sie den Assistenten testweise, list_available_tools aufzurufen.

Authentifizierung​

Jeder Tool-Aufruf gibt ErrorMessage: "Not authenticated" zurück​

Sie haben den Device Flow für die aktuelle MCP-Sitzung nicht abgeschlossen, oder Ihr Token ist abgelaufen und das Refresh-Token ist ebenfalls weg.

  1. Bitten Sie den Assistenten: „Authenticate me to tenant <tenant>." – dies ruft authenticate auf.
  2. Öffnen Sie die zurückgegebene Verifizierungs-URL, geben Sie den User-Code ein, schließen Sie die Browser-Anmeldung ab.
  3. Bitten Sie den Assistenten: „Check my authentication status." – dies ruft check_auth_status auf und speichert die Tokens.

Der Token-Status ist pro MCP-Sitzung (verschlüsselt über den HTTP-Header Mcp-Session-Id). Eine neue Claude-Code-Sitzung ist eine neue MCP-Sitzung – Sie authentifizieren sich einmal pro Sitzung, nicht einmal pro Aufruf.

check_auth_status gibt weiterhin isAuthenticated: false zurück​

Die Browser-Anmeldung ist noch nicht abgeschlossen, oder sie wurde gegen einen anderen Tenant abgeschlossen als der authenticate-Aufruf.

  • Stellen Sie sicher, dass Sie den Browser-Flow beendet haben (manche Identity Server zeigen eine „Success"-Seite; manche leiten stillschweigend weiter). Der User-Code ist kurzlebig – typischerweise 5–10 Minuten.
  • Ist der Code abgelaufen, rufen Sie authenticate erneut auf, um einen frischen zu erhalten.

Tokens waren gerade eben noch gültig, jetzt schlägt alles fehl​

Das Access-Token der Sitzung ist abgelaufen und das Refresh-Token ist ebenfalls weg (Serverneustart oder mehr als die Refresh-Token-Lebensdauer seit der letzten Aktivität).

Authentifizieren Sie sich erneut. Die Sitzung behält den MCP-Sitzungsidentifikator bei, sodass keine erneute Registrierung mit claude mcp nötig ist.

Incompatible auth server: does not support dynamic client registration​

Der MCP-Client (Claude Code) benötigt für interaktives OAuth RFC 7591 Dynamic Client Registration, aber der Identity Service bewirbt keinen registration_endpoint. Entweder ist der bereitgestellte Identity Service älter als die DCR-Unterstützung, oder die Registrierung wurde mit OCTO_IDENTITY__DYNAMICCLIENTREGISTRATION__ENABLED=false deaktiviert.

Fallen Sie auf den Device Flow (authenticate-Tool) zurück, oder aktivieren Sie DCR am Identity Service.

switch_tenant fällt auf die Device-Anmeldung zurück​

Der Token Exchange wurde verweigert – Ihr Benutzer hat keinen tenant-übergreifenden Zugriff auf den Ziel-Tenant. Provisionieren Sie ein ExternalTenantUserMapping für Ihren Benutzer im Ziel-Tenant (siehe Cross-Tenant Authentication), oder schließen Sie die angebotene Device-Flow-Anmeldung gegen diesen Tenant ab.

Tenant-Auflösung​

ErrorMessage: "No tenant could be resolved"​

Das Tool benötigte einen Tenant, aber keiner der beiden Wege wurde angegeben:

  • Fügen Sie dem Aufruf tenantId hinzu – jedes tenant-bezogene Tool akzeptiert es. Best Practice.
  • Oder registrieren Sie den Legacy-Endpunkt – /{tenantId}/mcp steckt den Tenant in die URL selbst.

Tool lief, operierte aber gegen den falschen Tenant​

Sie haben wahrscheinlich den Legacy-Endpunkt /{tenantId}/mcp registriert und dann einen anderen tenantId als Parameter übergeben. Der Parameter gewinnt (Priorität 1), das Ergebnis ist also korrekt, aber unerwartet, falls Sie annahmen, die URL sei maßgeblich.

Wechseln Sie dazu, den tenantlosen /mcp-Endpunkt zu registrieren und tenantId explizit pro Aufruf zu übergeben.

Destruktive Operationen​

ErrorMessage: "Refusing to delete '...' without confirm=true."​

Das ist beabsichtigt – destruktive Tools verweigern die Ausführung, sofern Sie nicht confirm: true übergeben. Der KI-Assistent sollte Sie um eine explizite Zustimmung bitten, bevor er den Parameter hinzufügt. Wenn Sie fortfahren möchten, weisen Sie den Assistenten entsprechend an:

Yes, go ahead — set confirm to true.

Es gibt keinen globalen Override. Jeder destruktive Aufruf benötigt seine eigene Bestätigung.

Dateiübertragungen​

Upload gibt 404 / 410 zurück​

Die Reservierung ist abgelaufen. Reservierungen und Uploads leben 30 Minuten, dann bereinigt sie der Hintergrund-Sweeper.

Rufen Sie prepare_file_upload erneut auf, um einen frischen transferId zu erhalten, und wiederholen Sie das PUT.

Upload gibt 413 Payload Too Large zurück​

Das harte 5-GiB-Limit wurde überschritten. Teilen Sie das Payload auf, oder verwenden Sie einen anderen Mechanismus für die Daten (z. B. octo-cli für Tenant-Dumps über 5 GiB, oder direkten Backend-Zugriff).

Download-URL liefert mitten in der Übertragung ein Connection reset​

Die Reservierung ist zwischen dem Tool-Aufruf und dem Download abgelaufen. Führen Sie das Export-/Dump-Tool erneut aus, um einen frischen transferId zu erhalten.

import_ck_model meldete Erfolg, aber get_available_models listet es weiterhin nicht auf​

get_available_models liest aus einem tenant-spezifischen Cache, der nach einem Import kurzzeitig veraltet sein kann. Die zuverlässige Quelle der Wahrheit ist get_ck_library_status:

{ "tool": "get_ck_library_status", "parameters": { "tenantId": "..." } }

Es meldet die tatsächlich geladene Version und den modelState. Warten Sie einen Moment, falls die Engine noch validiert, und rufen Sie dann erneut auf.

Dienstverwaltete CK-Modelle​

import_ck_from_catalog meldete Erfolg, aber das Modell ist nicht geladen​

Dienstverwaltete CK-Modelle – alles unter System.*, z. B. System.Communication, System.StreamData, System.Reporting, System.UI, System.Ai, System.Bot, System.Identity, System.Notification – können nicht mit import_ck_from_catalog geladen werden. Das Tool gibt IsSuccess: true mit "Enqueued 0 import job(s)" zurück und tut stillschweigend nichts. Das ist konsistent (das Modell gehört dem entsprechenden Backend-Dienst), aber irreführend.

Verwenden Sie stattdessen das passende enable_<feature>-Tool:

ModellTool
System.Communication-*enable_communication
System.StreamData-*enable_stream_data
System.Reporting-*enable_reporting
System.UI-*(noch kein MCP-Tool – über Studio oder octo-cli installieren)

Für benutzerverwaltete CK-Modelle (Basic.*, Industry.*, benutzerdefinierte Tenant-Modelle) funktioniert import_ck_from_catalog wie erwartet.

Aggregations- & Query-Tools​

ErrorMessage: "Aggregation requires at least one column"​

Übergeben Sie mindestens einen Eintrag im aggregations-Array. count benötigt keinen attributePath; alles andere schon.

ErrorMessage: "Aggregation alias '...' is not unique"​

Zwei Spalten im selben Aufruf erzeugten denselben Alias. Benennen Sie entweder eine explizit über alias um, oder ändern Sie die Funktion/den Pfad, sodass sich der Standard-Alias unterscheidet. Standard-Aliase folgen <function>_<sanitised-path> (z. B. avg_Power).

ErrorMessage: "groupBy paths must be non-empty / contain no duplicates"​

Prüfen Sie die groupByAttributePaths-Liste – leere Strings, Nulls und Duplikate werden alle im Voraus abgewiesen, bevor der Aufruf die Engine erreicht.

Streamdaten-Tool gibt "Archive not found" oder "Stream data not enabled" zurück​

Die vierstufige Kaskade zur Streamdaten-Auflösung ist an einem dieser Schritte fehlgeschlagen:

  1. Tenant nicht gefunden
  2. Streamdaten-CK-Modell in diesem Tenant nicht aktiviert → enable_stream_data ausführen
  3. Archiv-Runtime-Store nicht initialisiert
  4. archiveRtId existiert nicht → mit get_archive_storage_stats verifizieren

Die Fehlermeldung sagt Ihnen, welche Stufe fehlgeschlagen ist.

CK-Typ- / Entity-Fallstricke​

update_entity gibt IsConflict: true zurück​

Ein anderer Writer hat die Entität seit Ihrem letzten Lesen geändert. Die Antwort trägt das aktuelle Entity und CurrentRtVersion – rebasen Sie Ihre Änderung und rufen Sie update_entity erneut mit expected_version: <CurrentRtVersion> auf. Siehe Tool reference → Optimistic Locking.

ErrorMessage: "Invalid CkTypeId" beim Konstruieren einer Typ-ID​

CkTypeId ist Name-VersionUint, nicht SemVer. "MyType-1" ist gültig; "MyType-1.0.0" wirft, weil die Version als uint geparst wird.

ErrorMessage: "Invalid OctoObjectId" bei rtId​

OctoObjectId ist ein 24-Zeichen-Hex-String (MongoDB-ObjectId). Buchstaben außerhalb von [0-9a-fA-F] werden mit diesem Fehler abgewiesen. Beispielhafte reale Form: 507f1f77bcf86cd799439011.

Wo Sie als Nächstes suchen sollten​

  • get_tool_details(name) – vollständige Tool-Beschreibung, Parameter-Schema, Beispiele
  • list_available_tools – was der Server aktuell anbietet (nützlich nach einem Versions-Upgrade)
  • /health, /health/ready, /health/live – serverseitige Health-Probes