← Cloudflare Workers VPC / workers-vpc / reference

Řešení problémů a ladění

Řešení problémů a ladění chyb obvykle souvisejících s Workers VPC.

Kódy chyb spojení

Když se Workers VPC nemůže připojit k vaší privátní službě, fetch() vyvolá výjimku s chybovým kódem popisujícím, co se pokazilo. Tyto chybové kódy jsou vidět také v Metriky kartě vaší VPC Service v Cloudflare dashboardu.

Chyby jsou rozděleny do tří kategorií podle pravděpodobné příčiny. Tyto kategorie odpovídají popiskům zobrazeným v Metriky kartě vaší VPC Service v dashboardu.

Bad Upstream : Váš tunel nebo soukromá služba není dostupná. Zkontrolujte stav tunelu, dostupnost služby a konfiguraci sítě a TLS.
Klient : Příčinou selhání je konfigurace vaší VPC Service nebo kód Workeru. Zkontrolujte cílový hostname a chování požadavků Workeru.
Interní : Jde o problém na straně infrastruktury Cloudflare. Pokud přetrvává, kontaktujte podporu Cloudflare.

Chyby Bad Upstream

Tyto chyby znamenají, že se Cloudflare pokusil dosáhnout vaší privátní služby, ale připojení selhalo. Tunel může být nedostupný, služba nemusí naslouchat na daném portu, nebo mezi Cloudflare a vaším origin serverem dochází k problému se sítí či TLS.

Kód chyby	Popis	Doporučená oprava
`connection_refused`	Vaše privátní služba odmítla TCP připojení.	Ověřte, že vaše služba běží a naslouchá na očekávaném portu. Zkontrolujte pravidla brány firewall.
`connection_terminated`	Vaše služba ukončila připojení dříve, než byla přijata odpověď.	Zkontrolujte logy služby, zda neobsahují pády nebo vyčerpání prostředků.
`connection_timeout`	Vypršel časový limit pokusu o připojení k vaší službě.	Ověřte, že je vaše služba z tunelu dostupná. Zkontrolujte síťovou latenci nebo pravidla brány firewall, která mohou blokovat provoz.
`connection_limit_reached`	Bylo dosaženo maximálního počtu souběžných připojení k vaší službě.	Škálujte svou službu tak, aby zvládla více připojení, nebo snižte souběžnost připojení ve svém Workeru.
`destination_unavailable`	Vaše služba je považována za nedostupnou.	Ověřte, že váš tunel běží a že je vaše služba v pořádku.
`destination_not_found`	Pro tento požadavek se nepodařilo určit trasu.	Zkontrolujte, že konfigurace vaší VPC Service odkazuje na platného hostitele a že je váš tunel nastaven tak, aby na něj směroval provoz.
`destination_ip_prohibited`	Cílová IP adresa je zakázaná.	Ověřte, že je IP adresa nakonfigurovaná pro vaši VPC Service správná a není na seznamu zakázaných.
`destination_ip_unroutable`	K cílové IP adrese neexistuje síťová trasa.	Zkontrolujte, že je IP adresa správná a dostupná z vaší privátní sítě.
`proxy_loop_detected`	Požadavek by byl přeposlán zpět na stejný proxy server, čímž by vznikla smyčka.	Zkontrolujte konfiguraci VPC Service a tunelu, zda nedochází k cyklickému směrování.
`dns_error`	Překlad DNS selhal (například SERVFAIL).	Zkontrolujte, že hostname nastavený pro vaši VPC Service lze z vaší privátní sítě přeložit. Ověřte, že váš DNS resolver funguje správně. Přečtěte si Chyby tunelu pro běžné příčiny selhání DNS.
`dns_timeout`	Vypršel časový limit překladu DNS.	Zkontrolujte, že je váš DNS resolver dostupný a odpovídá. Zvažte nastavení vlastního DNS resolveru v nastavení vaší VPC Service.
`tls_protocol_error`	Při připojování k vaší službě došlo k chybě handshake TLS nebo protokolu.	Ověřte konfiguraci TLS vaší služby. Zkontrolujte, že jsou verze TLS a sady šifer kompatibilní.
`tls_certificate_error`	Ověření TLS certifikátu vaší služby selhalo.	Ujistěte se, že vaše služba předkládá platný certifikát od veřejně důvěryhodná certifikační autorita nebo Certifikát Cloudflare Origin CA.
`http_request_error`	Došlo k chybě požadavku HTTP.	Zkontrolujte logy služby, najdete v nich podrobnosti o příčině chybové odpovědi.
`http_upgrade_failed`	Selhal upgrade protokolu HTTP (například na WebSocket).	Ověřte, že vaše služba podporuje požadovaný upgrade protokolu.
`http_request_denied`	Požadavek byl před přeposláním zamítnut na základě zásady.	Zkontrolujte zásady přístupu a konfiguraci své služby.
`http_protocol_error`	Při komunikaci s vaší službou došlo k chybě protokolu HTTP.	Zkontrolujte, že vaše služba odpovídá platnou HTTP odpovědí.
`http_response_incomplete`	Vaše služba vrátila neúplnou HTTP odpověď.	Zkontrolujte, zda vaše služba neobsahuje problémy, kvůli kterým by mohla ukončovat spojení uprostřed odpovědi.

Chyby klienta

Tyto chyby signalizují problém v nastavení vaší VPC Service nebo v chování vašeho Workeru, nikoli v samotné privátní službě.

Kód chyby	Popis	Doporučená oprava
`dns_error` (NXDOMAIN)	Hostname nakonfigurovaný pro vaši VPC Service v DNS neexistuje.	Ověřte, že je hostname v konfiguraci vaší VPC Service správný a že pro něj existuje záznam DNS.
`connection_read_timeout`	Připojení bylo navázáno, ale v časovém limitu nedorazila žádná data.	Zkontrolujte kód Workeru, zda neobsahuje zaseknuté nebo pomalé požadavky. Ujistěte se, že Worker čte odpověď včas.
`connection_write_timeout`	Data se nepodařilo zapsat do spojení (buffery jsou plné).	Zkontrolujte kód Workeru, zda nezpracovává data odpovědi pomalu.
`rate_limited`	Byl překročen limit počtu připojení k tomuto originu.	Snižte rychlost nových připojení ze svého Workeru k této službě.

Interní chyby

Tyto chyby signalizují problém v infrastruktuře Cloudflare, který není způsoben vaší konfigurací ani vaší origin službou.

Kód chyby	Popis	Doporučená oprava
`proxy_internal_error`	V rámci proxy Cloudflare došlo k interní chybě.	Toto není způsobeno vaší konfigurací. Pokud chyba přetrvává, kontaktujte podpora Cloudflare ↗.

Chyby tunelu

Workers VPC může za běhu vracet chyby při připojování k privátním službám přes Cloudflare Tunnel.

Chybová zpráva	Podrobnosti	Doporučené opravy
`Error: ProxyError: dns_error`	Překlad DNS selhal při pokusu o připojení k vaší privátní službě přes tunel.	Tato chyba může nastat, pokud vaše `cloudflared` verze je zastaralá. Ujistěte se, že používáte `cloudflared` verzi 2025.7.0 nebo novější (doporučujeme nejnovější verzi). Viz Pokyny k aktualizaci Cloudflare Tunnel.
`Error: ProxyError: dns_error`	Cloudflare Tunnel lze nakonfigurovat s `http2` protokol (`TUNNEL_TRANSPORT_PROTOCOL:http2`), což funguje s Cloudflare Zero Trust (viz poznámka) provoz, ale brání DNS překladu z Workers VPC.	Workers VPC vyžaduje, aby se Cloudflare Tunnel připojoval pomocí Transportní protokol QUIC. Zkontrolujte, že odchozí provoz UDP na portu 7844 je ve vašem firewallu povolen.
Požadavky, které nezůstávají v rámci VPC	Požadavky Workeru pomocí `.fetch()` s veřejným hostname směrují mimo VPC na hostname nastavený pro VPC Service.	Ujistěte se, že kód Workeru i VPC Service používají pro backendové služby interní hostname VPC, nikoli veřejný hostname.

Chyby oprávnění

Pokud nemůžete v dashboardu nebo přes Wrangler zobrazit, vytvořit nebo svázat VPC Services a tunely, ověřte, že váš uživatel má potřebné role.

Workers VPC používá následující role účtu:

Connectivity Directory Read pro zobrazení Workers VPC Services a Tunnels.
Connectivity Directory Bind pro výpis, čtení a navázání VPC Services ve Workers.
Connectivity Directory Admin pro vytváření, aktualizaci a mazání VPC Services a přímé navázání na tunely prostřednictvím VPC Network binding.

Definice rolí najdete v Role.

Pokud jste své role nedávno aktualizovali a příkazy stále selhávají, obnovte ověření Wrangler:

npx wrangler logout
npx wrangler login

Pokud se ověřujete pomocí API tokenu (CLOUDFLARE_API_TOKEN), ujistěte se, že token patří uživateli s požadovanými rolemi.