07/Documentation
Fehlerbehebung für persistente Agenten
Ein persistenter Agent, der nicht erscheint oder Nicht erreichbar meldet: die ersten Prüfschritte, alle Ursachen samt Behebung, die Doctor-Zeilen und auftretende Sonderfälle
Experimentell. Das Übertragungsprotokoll, das SDK und diese Seite können sich in einer späteren Minor-Version ändern, oder die Funktion wird entfernt. Persistente Agenten beschreibt, was über den Verbleib entscheidet.
Ein Durable Agent, der nicht erscheint, Unreachable anzeigt oder nicht auf ein Antippen reagiert: Drei Befehle finden die Ursache, und eine Ursachentabelle sowie eine Liste von Fällen liefern die Fehlerbehebung. Fehlerbehebung behandelt Collie insgesamt.
Erste Prüfungen
Führen Sie diese drei Befehle in dieser Reihenfolge aus:
collie durable list
collie doctor
collie logs| Befehl | was er für einen Durable Agent anzeigt |
|---|---|
collie durable list | Eine Zeile pro Eintrag in sources.json, mit dem Status, den die laufende Bridge ihm zuweist: loaded, not loaded (restart to apply), refused (<status>) oder bridge not answering. loaded bedeutet, dass die Bridge den Eintrag geladen hat. Es bedeutet nicht, dass der Durable Agent antwortet. Ein not loaded wird auch angezeigt, wenn die Bridge HTTP 400 für den Namen zurückgibt |
collie doctor | Fragt den Durable Agent selbst ab. Gibt die Zeilen von Doctor-Zeilen für Durable Agents aus und nennt die fehlschlagende Prüfung mit einer Fehlerbehebung |
collie logs | Die Boot-Zeile jedes Durable Agent, [bridge] program "desk": durable, private socket /run/user/1000/desk/app.sock, und deren Grund, wenn eine Einstellung eine Regel verletzt. Ein ungültiges sources.json gibt [bridge] FATAL: aus. Ein fehlgeschlagener Lesevorgang gibt [state] poll failed, marking disconnected: <reason> einmal pro Ausfall aus. Zeilen, die mit [durable] beginnen, nennen eine Versionsverweigerung, einen veralteten Lead, verworfene Elemente und ein gelöschtes Protokoll |
Das Smartphone zeigt weniger an. Eine Zeile eines Durable Agent lautet Starting oder Unreachable und nennt keinen Grund. Eine Verweigerung der Protokollversion hat einen eigenen Begriff, Version mismatch, und ein Warnfeld auf der Startseite des Durable Agent. Ein verweigertes Token hat eigene Begriffe in der Verbindungsleiste. collie doctor und collie logs nennen jeden anderen Grund.
Die Tabelle der Ursachen
Wenn Collie einen Durable-Agenten nicht erreichen kann, startet das restliche Collie trotzdem, und der Durable-Agent wird mit einer Ursache als nicht erreichbar angezeigt.
Eine Ursache nennt die Umgebungsvariable, selbst wenn der Durable-Agent ein Eintrag von sources.json ist. Lesen Sie COLLIE_DURABLE_SOCKET als socket des Eintrags, COLLIE_DURABLE_URL als sein url und COLLIE_DURABLE_TOKEN als sein token. Die Behebung für einen Eintrag liegt in sources.json. Die Behebung für die reine Durable-Form liegt in .env, danach collie restart.
Die Einstellung verletzt eine Regel
Collie meldet diese, ohne den Durable-Agenten anzuwählen. Regeln in sources.json-Einträgen werden beim Start der Bridge ebenfalls abgewiesen (Ein Tippfehler in sources.json).
| Grund | Bedeutung und Behebung |
|---|---|
COLLIE_DURABLE_SOCKET is not set | Die reine Durable-Form hat keinen Socket-Pfad. Setzen Sie ihn oder setzen Sie die URL mit ihrem Token |
COLLIE_DURABLE_SOCKET must be an absolute path | Geben Sie den vollständigen Pfad an, beginnend mit / |
COLLIE_DURABLE_SOCKET is longer than 103 bytes | Kürzen Sie den Pfad. Halten Sie ihn unter $XDG_RUNTIME_DIR |
the private socket transport is not available on Windows; set COLLIE_DURABLE_URL and COLLIE_DURABLE_TOKEN instead | Windows bietet keinen Socket-Transport. Verwenden Sie eine URL und ein Token |
COLLIE_DURABLE_SOCKET and COLLIE_DURABLE_URL are both set; set the socket, or the URL with its token, not both | Die reine Durable-Form hat beides erhalten. Behalten Sie einen Transport bei |
COLLIE_DURABLE_URL is set without COLLIE_DURABLE_TOKEN; the durable agent refuses a caller with no token | Die reine Durable-Form hat eine URL und kein Token erhalten. Setzen Sie das Token |
COLLIE_DURABLE_TOKEN is set without COLLIE_DURABLE_URL; a token is only sent to a URL | Die reine Durable-Form hat ein Token und keine URL erhalten. Setzen Sie die URL oder entfernen Sie das Token |
COLLIE_DURABLE_URL is longer than 2048 bytes | Kürzen Sie die URL auf die Basisadresse des Durable-Agenten |
COLLIE_DURABLE_URL is not a URL | Schreiben Sie es als https://host |
COLLIE_DURABLE_URL must start with https:// | Jedes Schema außer https:// wird abgewiesen. Ein einfaches http:// hat unten eine eigene Zeile |
COLLIE_DURABLE_URL uses plain http to <host>, so the token would cross the network unencrypted; use https://, or http://127.0.0.1:<port> for wrangler dev | Verwenden Sie https://. Einfaches http ist für 127.0.0.1 oder localhost mit Port gedacht |
COLLIE_DURABLE_URL uses plain http on loopback without a port; name the port, for example http://127.0.0.1:8801 | Fügen Sie den Port hinzu |
COLLIE_DURABLE_URL must not carry a user name or password; the token goes in COLLIE_DURABLE_TOKEN | Entfernen Sie Benutzername und Passwort aus der URL |
COLLIE_DURABLE_URL must not carry a query or a fragment | Entfernen Sie den Teil ? und den Teil # aus der URL |
COLLIE_DURABLE_URL names the durable agent's base only; leave out /session/v1, the adapter adds it | Entfernen Sie /session/v1 aus dem Pfad |
COLLIE_DURABLE_TOKEN is <n> bytes; it must be at least 32 bytes, for example 64 hex characters from openssl rand -hex 32 | Erstellen Sie ein längeres Token und weisen Sie dem Durable-Agenten dasselbe zu |
COLLIE_DURABLE_TOKEN must be printable ASCII with no spaces | Entfernen Sie Leerzeichen und sonstige Zeichen aus dem Token |
COLLIE_DURABLE_TOKEN is longer than 4096 bytes | Ein derart langer Header ist ein Fehler. Verwenden Sie ein kürzeres Token |
Der Durable-Agent antwortet nicht oder antwortet fehlerhaft
| Grund | Bedeutung und Behebung |
|---|---|
no socket at <path> | Unter diesem Pfad befindet sich noch nichts. Starten Sie den Durable-Agenten oder korrigieren Sie den Pfad |
cannot check <path>: <message> | Collie konnte den Pfad nicht lesen. Machen Sie ihn für Ihren Benutzer lesbar |
socket-not-private: <check> | Das Durchlaufen des Pfads schlug fehl, und der Text nach dem Doppelpunkt nennt den Teil. Die Datenschutzprüfung schlägt fehl enthält die üblichen Fälle |
connection refused | Nichts lauscht. Ein abgestürzter Durable Agent kann seine Socket-Datei hinterlassen: Eine verwaiste Socket-Datei. Über https lauscht nichts an der URL |
no answer within <n>ms | Der Durable Agent reagiert nicht oder ist kalt. Collie wartet 1000 ms an einem Socket und 5000 ms über https |
tls refused: <message> | Das Zertifikat der URL wird abgelehnt. Collie bietet keine Option, um die Prüfung zu überspringen |
the host name does not resolve | Der Hostname in der URL ist falsch oder Ihr Netzwerk kann ihn nicht erreichen |
token-refused: the durable agent answered 401 oder 403 | Der Durable Agent hat das Token abgelehnt. Der Durable Agent hat das Token abgelehnt |
too-large | Der Durable Agent hat mit mehr Daten geantwortet, als Collie liest: 16 KiB für hello, 4 MiB für einen Snapshot. Verkleinern Sie seine Antwort |
incompatible: the durable agent speaks 2..3, this Collie speaks 1..1 | Die Versionsbereiche überschneiden sich nicht. Aktualisieren Sie die ältere Seite. collie doctor zeigt beide Bereiche, und das Protokoll enthält eine Zeile pro Bereich |
incompatible: not a durable agent | Etwas anderes antwortet unter diesem Pfad oder dieser URL. Richten Sie den Eintrag auf den Durable Agent aus |
incompatible: the durable agent asks for a token | Ein Durable Agent an einem Socket erwartet ein Token, das ein Socket jedoch nie überträgt. Aktualisieren Sie die ältere Seite oder erreichen Sie ihn per URL mit einem Token |
unreadable hello: <detail> oder unreadable snapshot: <detail> | Der Durable Agent hat ein Dokument gesendet, das das Protokoll nicht erlaubt. Lesen Sie das eigene Protokoll des Durable Agent |
the durable agent answered <status> oder the durable agent answered 409 <code> | Der Durable Agent hat mit einem Status geantwortet, den das Protokoll hier nicht verwendet. Lesen Sie das eigene Protokoll des Durable Agent |
starting | Der Durable Agent läuft und meldet, dass er nicht bereit ist, oder antwortet mit 503. Collie fragt bei der nächsten Abfrage erneut an |
Doctor-Zeilen für Durable Agents
collie doctor stellt jedem Durable Agent dieselben Fragen wie die Bridge in der gleichen Reihenfolge. Es sendet ausschließlich hello.
Jeder Eintrag von sources.json erhält einen Block aus sechs Zeilen, geschrieben als durable-socket:desk für einen Durable Agent namens desk. Eine Zeile sources vor den Blöcken prüft die Datei, und eine Zeile durable-lead folgt ihnen. Ein reines Durable-Collie gibt dieselben sechs Zeilen ohne Suffix aus, und seine Zeile mux lautet durable, see the durable-* lines.
| Zeile | grün | Warnung oder rot |
|---|---|---|
sources | 2 durable agents in <path>, mode 0600 | Rot, wenn die Datei nicht geparst werden kann. Der Korrekturhinweis besagt, dass die Bridge nicht startet, solange die Datei fehlerhaft ist. Rot, wenn Gruppe oder andere die Datei lesen können, mit chmod 600 als Korrekturhinweis, da ein Eintrag ein Token enthalten kann |
durable-env | transport: private socket mit dem Pfad oder transport: https with a bearer token | Rot, wenn die Einstellung eine Regel aus die Ursachentabelle verletzt |
durable-socket | Der Pfad ist ein Socket, gehört Ihnen, Modus 0600, in einem Ihrer Ordner mit Modus 0700, kein Link auf dem Pfad dorthin | Rot, und die Zeile nennt die fehlgeschlagene Prüfung: nicht vorhanden, nicht lesbar, kein Socket, ein Symlink, kein Ordner, Ordner eines anderen Eigentümers, Ordner mit falschem Modus, übergeordneter Ordner für andere beschreibbar, Socket eines anderen Eigentümers oder Socket mit offenem Modus. Bei einem Durable Agent hinter https übersprungen |
durable-url | Die Adresse, https oder Loopback-http, und ihre Länge in Bytes | Rot, wenn die URL eine Regel verletzt. Bei einem Socket übersprungen |
durable-token | set, <n> bytes. Collie gibt den Wert niemals aus | Rot, wenn das Token eine Regel verletzt. Bei einem Socket übersprungen |
durable-hello | Der Durable Agent hat geantwortet. Beide Bereiche, die vereinbarte Version | Rot mit der Ursache: Das Token wurde abgewiesen, nichts hat geantwortet, eine Antwort stammt nicht von einem Durable Agent, der Durable Agent verlangt ein Token über ein Socket, hello ist nicht lesbar oder Bereiche überschneiden sich nicht. Bei einer Bereichsabweichung werden beide Bereiche angezeigt. |
durable-ready | ready, der Hostname des Durable Agents und seine Epoche | Eine Warnung, wenn der Durable Agent meldet, dass er noch nicht bereit ist |
durable-lead | Der Lead ist neu genug, um die Fragekarte anzuzeigen | Siehe In einer Crew |
Eine fehlschlagende Zeile stoppt die nachfolgenden Zeilen. Sie werden als übersprungen mit dem Grund fix the row above first ausgegeben, da Collie einen Durable Agent nie über ein Socket abfragt, das die Datenschutzprüfung nicht besteht, oder mit einem Token, das gegen dessen Regel verstößt. Eine übersprungene Zeile ist kein Fehler.
Fälle
Jeder Fall nennt Symptom, Ursache und Behebung.
Ein Tippfehler in sources.json
Collie ist nicht erreichbar, nicht nur ein einzelner Durable Agent: Das Telefon kann keine Verbindung herstellen. collie logs endet mit [bridge] FATAL:, dem Dateipfad, dem Eintrag und dem Feld.
Die Bridge liest sources.json beim Start und bricht ab bei einem unbekannten Feld, einem kind, das nicht durable ist, einem Namen, der die Regel verletzt, einem doppelt vergebenen Namen, socket und url gemeinsam, keinem von beiden, einem url ohne token oder einem token mit einem socket. Korrigieren Sie die Datei und führen Sie dann collie restart aus. collie doctor zeigt dieselbe Meldung in der Zeile sources.
Kann die Bridge den Eintrag nicht benennen (er ist kein Objekt, enthält ein unbekanntes Feld oder der Name verletzt die Regel), zählt sie ab 0 und schreibt für den zweiten Eintrag entry 1. collie durable attach zählt ab 1 und schreibt für denselben Eintrag entry 2. Beide geben das betroffene Feld an. Sobald der Name gültig ist, schreibt die Bridge den Namen: entry "desk".
attach und detach weigern sich, eine Datei zu schreiben, die sie nicht lesen können; ein Tippfehler gefährdet somit nie Ihre übrigen Einträge. Sie brechen mit dem Exit-Code 1 ab.
Ein Durable Agent erscheint nach attach nicht
Auf dem Telefon ist kein Durable Agent sichtbar und collie durable list meldet not loaded (restart to apply).
attach und detach schreiben nur sources.json. Die Bridge liest dies beim Start. Führen Sie collie restart aus oder übergeben Sie dem Verb beim nächsten Mal --restart. Bleibt not loaded nach einem Neustart bestehen, prüfen Sie collie logs: list formuliert einen HTTP-Status 400 von der Bridge genauso wie einen 404.
Die Datenschutzprüfung schlägt fehl
Es wird socket-not-private: the socket's folder /tmp/hello has mode 0755, not 0700 angezeigt und die Doctor-Zeile durable-socket ist rot.
Collie verbindet sich nur dann mit einem Socket, wenn der gesamte Pfad privat ist. Typische Ursachen sind ein Ordner mit den Rechten 0755, ein Socket direkt in /tmp oder einem anderen gemeinsam genutzten Ordner sowie ein symbolischer Link im Pfad. Ein symbolischer Link wird leicht übersehen: /var/run verweist auf vielen Linux-Hosts auf /run, sodass ein Pfad, der mit /var/run/ beginnt, mit /var/run is a symlink fehlschlägt. Verwenden Sie den realen Pfad.
Wenden Sie chmod 700 auf den Ordner des Sockets an oder verschieben Sie das Socket nach $XDG_RUNTIME_DIR. Die Regeln finden Sie in Sicherheit eines persistenten Agenten. Ein mit dem SDK erstellter Durable Agent verweigert den Start in einem bestehenden Ordner, dessen Rechte nicht 0700 lauten, und gibt dies selbstständig aus.
Eine verwaiste Socket-Datei
Es wird connection refused an einem Socket angezeigt, und die Datei ist vorhanden.
Ein abgestürzter Durable Agent hinterlässt seine Socket-Datei, und kein Prozess nimmt Verbindungen darüber an. Starten Sie den Durable Agent erneut. Das SDK entfernt eine verwaiste Socket-Datei vor dem Verbindungsaufbau und bricht mit another instance is already listening ab, wenn das Socket aktiv ist. Löschen Sie die Datei nur dann manuell, wenn Ihr Durable Agent sie nicht selbst bereinigt.
Ein Name, der bereits für eine Terminalsitzung vergeben ist
Die Bridge bricht beim Start mit the name is the terminal session's own; pick another ab oder eine Terminalsitzung fehlt auf dem Telefon.
Ein Durable Agent darf nicht denselben Namen tragen wie das Terminal, aus dem Collie ausgeführt wird. Dieser Name lautet bei den meisten Installationen default, und bei einer reinen Durable-Installation von Collie entspricht default dem Namen des jeweiligen Durable Agents. Die Bridge bricht beim Start ab und nennt den betroffenen Eintrag. Eine Herdr-Sitzung mit dem Namen eines Durable Agents stellt einen weiteren Fall dar: Der Durable Agent behält den Namen, das Telefon zeigt diese Sitzung nicht an und das Protokoll vermerkt dies einmalig. Benennen Sie einen der beiden Einträge um.
Eine dauerhafte Durable-ready-Warnung
durable-ready wird bei jeder Ausführung von collie doctor als Warnung angezeigt.
Der Durable Agent antwortet mit hello und meldet ready: false. Das Telefon zeigt den Status Starting an. Ein Durable Agent meldet erst dann Bereitschaft, nachdem er seine Konversationen aufgebaut und seine offenen Fragen erneut vorgelegt hat. Prüfen Sie das eigene Protokoll des Durable Agents, um zu sehen, worauf er wartet.
Der Durable Agent bricht beim Start an der Nachfahrenprüfung ab
Der Durable Agent bricht beim Start mit the descendant check needs Bun on Linux to read the peer of a socket; pass callerCheck: "off" to run without it ab.
Die Prüfung setzt Bun unter Linux voraus. Führen Sie den Durable Agent unter macOS mit Node aus oder übergeben Sie callerCheck: "off" an openCollie und prüfen Sie vorher was die Prüfung absichert. Der Fehler stammt vom Durable Agent. Collie ist daran nicht beteiligt.
Eine Frage erscheint nach einem Neustart erneut
Sie sehen dieselbe Frage nach dem Neustart des Durable Agent erneut oder eine Karte mit dem Hinweis, dass sie bereits beantwortet wurde.
Eine Antwort auf eine Frage von vor dem Neustart erhält too-late, die Karte zeigt dies an und verschwindet. Ein Durable Agent, der die ID der Frage aus seinem Toolaufruf ableitet, stellt dieselbe Frage erneut; eine über den Neustart hinweg gesendete Antwort kommt also an und das Tool wird einmal ausgeführt. Ein Durable Agent, der jedes Mal eine neue ID erzeugt, stellt für denselben Toolaufruf eine neue Frage. Die Karte zeigt sie an, und Collie sendet keinen zweiten Push, da der Push-Schutz an den Toolaufruf gekoppelt ist. Der Schutz erlaubt außerdem 3 Pushes pro Konversation und Minute, 10 pro Host und Minute sowie 30 pro Host und Stunde. Der Push, der der 31. in einer Stunde wäre, wird zu einem einzelnen Sammel-Push für diesen Host, und der Host sendet bis eine Stunde danach keine weiteren. Eine Karte wird immer angezeigt.
403 caller-refused
Auf dem Telefon erscheint der Hinweis, dass die Antwort oder Nachricht abgelehnt wurde, und die Begründung des Durable Agent lautet 403 caller-refused.
Die Nachfahrenprüfung des Durable Agent hat den Aufrufer abgewiesen. Sie weist den Durable Agent selbst ab, jeden vom Durable Agent gestarteten Prozess sowie Aufrufer, die sie nicht von diesen unterscheiden kann. Collie fällt auf die Seite des Durable Agent, wenn der Durable Agent oder ein von ihm ausgeführtes Tool den Collie-Prozess gestartet hat und dieser Prozess weiterhin dessen Kindprozess ist. Starten Sie Collie von außerhalb des Durable Agent und versuchen Sie es erneut.
Erneut versuchen und eine Antwort, die möglicherweise angewendet wurde
Sie sehen „Nicht sicher, ob die Antwort ankam“ mit einer Schaltfläche „Erneut versuchen“, und nach dem Antippen „Wurde möglicherweise bereits angewendet. Prüfen Sie den Chat.“
Ein Timeout, eine getrennte Verbindung oder ein 5xx-Fehler nach dem Absenden der Antwort bedeutet, dass sie möglicherweise angekommen ist. „Erneut versuchen“ sendet dieselbe Anfrage-ID, sodass der Durable Agent mit replayed antwortet und die Frage niemals doppelt auflöst. Wenn die Frage bereits geschlossen ist, hat der erste Versuch sie möglicherweise geschlossen; daher fordert das Telefon dazu auf, den Chat zu prüfen. Ein Sendevorgang, ein Abbruch und das Antippen einer Schaltfläche drücken dasselbe mit eigenen Worten aus.
Der Durable Agent hat das Token abgelehnt
In der Verbindungsleiste erscheint „Der Durable Agent hat das Token abgelehnt. Prüfen Sie COLLIE_DURABLE_TOKEN auf diesem Peer.“, und der Grund ist token-refused.
Der Durable Agent hat das Token mit 401 oder 403 beantwortet. Die häufigste Ursache ist eine Rotation, bei der eine Seite zuerst geändert wurde. Der Text auf dem Telefon nennt COLLIE_DURABLE_TOKEN auch für einen Eintrag von sources.json: Lesen Sie dies als token des Eintrags. Übergeben Sie dem Durable Agent das neue Token, bevor Sie Collie neu starten. Tokens beschreibt die Schritte zur Rotation. Ein 403 kann auch von einem Zugriffsproxy vor dem Durable Agent stammen.
Ein Wechsel zu „Nicht erreichbar“, der zwei Lesevorgänge erfordert
Sie sehen, dass ein Durable Agent für einen fehlgeschlagenen Lesevorgang auf „Bereit“ bleibt und dann zu „Nicht erreichbar“ wechselt.
Ein einzelner fehlgeschlagener Lesevorgang nach einem erfolgreichen behält das letzte Layout für diesen Abruf bei. Erst der zweite Fehlschlag in Folge schaltet den Durable Agent um. Ein abgewiesenes Token folgt derselben Regel. Ein Socket-Pfad, der die Rechteprüfung nicht besteht, ist die einzige Ausnahme: Er wird sofort angezeigt.
Über HTTPS wird ein Durable Agent, der ausgefallen ist oder das Token ablehnt, höchstens alle 10 s abgefragt, da jeder Versuch eine abgerechnete Anfrage ist. Über einen Socket beträgt der Mindestabstand zwischen zwei Lesevorgängen eines ausgefallenen Durable Agent 250 ms.
In einer Crew
Ein Durable Agent auf einem Crew-Mitglied wird auf dem Telefon der Leitung angezeigt; daher muss die Leitung wissen, was ein Durable Agent ist.
Eine Leitung älter als Version 1.21.0 listet die Konversationen des Durable Agent ohne die Fragekarte auf, und ihr Terminal-Reiter fragt eine Konversation ab, die kein Terminal besitzt. Auf dem Mitglied lässt sich das nicht beheben. Das Mitglied meldet dies selbst: collie doctor warnt in durable-lead, und das Protokoll erhält für jedes erkannte Release eine einzelne Zeile, [durable] the lead is 1.20.1; it shows durable panes without the question card and its Terminal tab polls; update the lead. Aktualisieren Sie die Leitung.
durable-lead | Meldung |
|---|---|
| übersprungen, keine Crew | Dieses System ist in keiner Crew, daher gibt es keine Leitung |
| übersprungen, Leitung | Dieses System ist die Leitung und zeigt seine eigenen Bereiche |
| übersprungen, kein Release | Die Leitung hat kein Release angegeben: ein Entwicklungs-Build, ein laufendes Update oder kein Aufruf seit dem Start der Bridge |
| Warnung | Die Leitung verwendet ein Release vor 1.21.0 |
| grün | Die Leitung ist Version 1.21.0 oder neuer |
Ein Mitglied, das älter als die Leitung ist, weist den umgekehrten Fehler auf. Das Telefon meldet: „Dieses System verwendet ein älteres Collie und kann hier keine Antworten annehmen. Aktualisieren Sie es oder antworten Sie im Durable Agent.“ Aktualisieren Sie dieses Mitglied.
Diese Seite auf GitHub bearbeiten