ai-tools/private-proxy-mcp
Watch
2
0
Fork
You've already forked private-proxy-mcp
 0
Code Issues 2 Pull requests 1 Projects Releases 5 Packages 2 Wiki Activity Actions
Page: Troubleshooting
Pages
ADR-Browser-Backend ADR-Browser-Identity-Playwright ADR-MCP-Go-SDK ADR-Rust-Proxy-Tauri ADR-Tunnel-Protocol Architecture CLI Compatibility Configuration Deployment Desktop-Proxy Development Home MVP-Acceptance Releases Security-MCP-Exposure Security-Network-Policy Shared-Key Troubleshooting
6 Troubleshooting
Forgeagent edited this page 2026-07-20 10:25:29 +02:00
Table of contents

Troubleshooting

Zuerst werden Prozessstatus und strukturierte Logs auf beiden Seiten geprüft:

curl --fail http://127.0.0.1:9334/health/live
curl --fail http://127.0.0.1:9334/health/ready
private-proxy-mcp version

live beweist nur einen laufenden MCP-Prozess. Readiness 503 mit not_ready bedeutet, dass kein verwendbarer privater Proxy verbunden ist. Zum Diagnostizieren temporär log.level: debug verwenden, ohne Payloads oder Secrets in zusätzliche Logs aufzunehmen.

Connector-Authentisierung

Symptome: wiederholter Reconnect, serverseitig error_code=auth_error, HTTP 401 am /connector, Readiness bleibt 503.

  1. Prüfen, dass private_proxy.shared_key auf beiden Hosts aus derselben Secret-Version geladen und danach beide Prozesse neu gestartet wurden.
  2. Auf unsichtbaren Whitespace oder eine mitkopierte Zeilenumbruchssequenz im Secret Store prüfen, ohne den Wert auszugeben.
  3. Sicherstellen, dass die URL exakt /connector und einen expliziten Port enthält.
  4. TLS-Fehler separat beheben; insecure_skip_verify nicht als Auth-Fix verwenden.

Nach einer Rotation wird zuerst der Server und danach der private Proxy mit dem neuen Key gestartet.

TLS und Upgrade

Symptome: TLS handshake with connector, Zertifikatsfehler, HTTP 426/505 oder invalid upgrade response.

  • CA-Datei, Zertifikatskette, Gültigkeitszeit und tls_server_name mit dem URL-Host abgleichen.
  • Der Edge-Proxy muss HTTP/1.1, Connection: Upgrade, Upgrade und die Private-Proxy-MCP-*-Header durchreichen. HTTP/2/3 am Connector-Upstream deaktivieren.
  • Response-Buffering, kurze Proxy-Timeouts und Body-Injektion für Status 101 deaktivieren.
  • Port 9335 vom privaten Host aus erreichbar machen; Port 9334 ist dafür irrelevant.

Reconnect-Schleifen

connector unavailable; retrying vor einem erfolgreichen Upgrade nutzt exponentiellen Backoff zwischen backoff_initial und backoff_max mit Jitter. connector session ended; reconnecting nach einer etablierten Session nutzt reconnect_delay.

  • DNS, Firewall, Listener und Edge-Proxy prüfen.
  • goaway(replaced) zeigt eine zweite Proxy-Instanz mit demselben Connector; nur die neueste Verbindung bleibt aktiv.
  • pong timeout weist auf einen toten Stream oder zu kurze Zwischenproxy- Idle-Timeouts hin. Diese müssen deutlich größer als Ping- plus Pong-Zeit sein.
  • Backoff nicht auf nahezu null reduzieren; die Ursache beheben, um Lastspitzen zu vermeiden.

Request-Timeouts und Abbrüche

deadline_exceeded kann vom MCP-Aufruf, der lokalen http.request_timeout-Grenze, Browser/Media-Limits oder der absoluten Tunneldeadline stammen. Der wirksame Wert ist jeweils das kleinste Limit und niemals mehr als die Tunnel-Deadline (Wire 1.1: 30m, Legacy: 120s). Bei langen Downloads hält bidirektionales Ping den Tunnel am Leben; der Proxy sendet zusätzlich progress-Frames.

  • DNS- und Connect-Latenz vom privaten Host zum Ziel messen.
  • dns_timeout, runtime.connect_timeout und request_timeout nur gezielt erhöhen; die Tunnelobergrenze bleibt bestehen.
  • Clientabbruch erzeugt cancelled; das ist kein Reconnect-Problem.
  • HTTP 4xx/5xx sind normale Antworten und nicht mit Transport-Timeouts zu verwechseln.

Truncation und Größenlimits

truncated: true bedeutet, dass ein gültiger HTTP-Responsebody am response_body_limit, decompressed_body_limit oder am maximalen Tunnel- Frame abgeschnitten wurde. response_too_large bedeutet, dass selbst keine sichere begrenzte Frame-Antwort erzeugt werden konnte. Die Metrik-/Eventklasse lautet truncation.

  • Zielabfrage enger formulieren oder einen kleineren Upstream-Response anfordern.
  • Limits nur zusammen mit Speicher-, Frame- und MCP-Client-Grenzen erhöhen.
  • Komprimierte Antworten nach dekomprimierter Größe beurteilen.
  • Große Media-/Screenshot-Ausgaben über die vorgesehenen kurzlebigen Artefakt-Links und Chunk-Reads beziehen.

Fehlender Proxy oder fehlende Tools

Symptome: Readiness 503, private proxy is unavailable, oder Media-/Browser- Tools fehlen in tools/list.

  • Beide Prozesse müssen laufen und die Connector-Session muss authentisiert sein.
  • Media-Tools erscheinen nur, wenn der Private Proxy media capability available loggt und die Capabilities im Connector-Upgrade mitgibt. Der MCP-Server führt yt-dlp nicht selbst aus.
  • Auto-Discovery: yt-dlp muss im PATH des Proxy-Prozesses liegen oder über media.yt_dlp_path erreichbar sein. media.enabled: false schaltet Media hart aus. Ein optionaler yt_dlp_version-Pin muss zur Binary passen.
  • Transcripts: Default-Kette ytdlp → innertube. Bei subtitles_missing / upstream_error greift InnerTube; translation_language braucht InnerTube. yt-dlp-CDN bleibt Host-Egress; InnerTube unterliegt http.network_policy.
  • Bei media capability unavailable den Log-Hinweis und yt_dlp_path prüfen; absoluten Pfad setzen, wenn die Binary nicht im PATH steht.
  • browser.enabled, Host-Allowlisten und Limits auf dem privaten Proxy prüfen. Eine nicht verfügbare Capability wird geloggt und nicht angekündigt.
  • Browser: executable_path/executable_version gegen --version prüfen. Bei backend: playwright zusätzlich playwright_node_path und playwright_sidecar_path. Details und OS-Setup: Browser-Tools.
  • Auf dem mcp-server ist bei aktivem Media artifact_base_url als HTTPS-URL erforderlich.
  • Nach Wiederherstellung eine neue tools/list-Abfrage ausführen; die Capability-Liste ist dynamisch.