← Cloudflare Workers VPC / workers-vpc / reference

Диагностика и отладка

Диагностика и устранение ошибок, часто возникающих при использовании Workers VPC.

Коды ошибок соединения

Если Workers VPC не может установить соединение с вашей частной службой, fetch() выбросит исключение с кодом ошибки, описывающим причину сбоя. Эти коды ошибок также отображаются в Метрики вкладке вашего VPC Service в панели управления Cloudflare.

Ошибки группируются в три категории по вероятной причине. Эти категории соответствуют меткам, отображаемым в Метрики вкладке вашего VPC Service в панели управления.

Bad Upstream : туннель или приватный сервис недоступен. Проверьте состояние туннеля, доступность сервиса и настройки сети или TLS.
Клиент : причина сбоя в конфигурации VPC Service или в коде Worker. Проверьте целевой хост и поведение запроса Worker.
Внутренний : неполадка на стороне инфраструктуры Cloudflare. Если она повторяется, обратитесь в поддержку Cloudflare.

Ошибки Bad Upstream

Эти ошибки означают, что Cloudflare попытался обратиться к вашему приватному сервису, но соединение не удалось установить. Возможно, туннель не работает, сервис не прослушивает порт, либо между Cloudflare и вашим источником возникла проблема с сетью или TLS.

Код ошибки	Описание	Рекомендуемое исправление
`connection_refused`	Ваша приватная служба отклонила TCP-соединение.	Убедитесь, что ваш сервис запущен и прослушивает ожидаемый порт. Проверьте правила брандмауэра.
`connection_terminated`	Ваш сервис закрыл соединение до получения ответа.	Проверьте логи сервиса на наличие сбоев или исчерпания ресурсов.
`connection_timeout`	Превышено время ожидания при попытке подключения к вашему сервису.	Убедитесь, что ваш сервис доступен из туннеля. Проверьте задержку сети или правила брандмауэра, блокирующие трафик.
`connection_limit_reached`	Достигнуто максимальное количество одновременных подключений к вашему сервису.	Масштабируйте свой сервис для обработки большего числа соединений либо снизьте параллелизм соединений в вашем Worker.
`destination_unavailable`	Ваша служба считается недоступной.	Убедитесь, что ваш туннель запущен, а сервис исправен.
`destination_not_found`	Не удалось определить маршрут для этого запроса.	Убедитесь, что конфигурация VPC Service указывает на действительный хост и что туннель настроен для маршрутизации трафика к нему.
`destination_ip_prohibited`	IP-адрес назначения запрещён.	Убедитесь, что IP-адрес, настроенный для вашего VPC Service, указан верно и не входит в список запрещённых.
`destination_ip_unroutable`	Маршрут сети до целевого IP-адреса отсутствует.	Убедитесь, что IP-адрес указан верно и доступен из вашей приватной сети.
`proxy_loop_detected`	Запрос был бы перенаправлен обратно на тот же прокси, создавая петлю.	Проверьте конфигурацию VPC Service и туннеля на предмет циклической маршрутизации.
`dns_error`	Сбой разрешения DNS (например, SERVFAIL).	Убедитесь, что имя хоста, настроенное для вашего VPC Service, разрешается из вашей приватной сети. Проверьте, что ваш DNS резолвер работает корректно. См. Ошибки туннеля типичные причины проблем с DNS.
`dns_timeout`	Истекло время ожидания разрешения DNS.	Убедитесь, что ваш DNS резолвер доступен и отвечает на запросы. Рассмотрите возможность настройки собственного DNS резолвера в параметрах VPC Service.
`tls_protocol_error`	При подключении к вашему сервису произошла ошибка TLS-рукопожатия или протокола.	Проверьте конфигурацию TLS вашего сервиса. Убедитесь, что версия TLS и наборы шифров совместимы.
`tls_certificate_error`	TLS-сертификат вашей службы не прошёл проверку.	Убедитесь, что ваш сервис предоставляет действительный сертификат от общепризнанный центр сертификации (CA) или Сертификат Cloudflare Origin CA.
`http_request_error`	Произошла ошибка HTTP-запроса.	Проверьте логи сервиса, чтобы выяснить причину ошибки в ответе.
`http_upgrade_failed`	Не удалось выполнить обновление протокола HTTP (например, до WebSocket).	Убедитесь, что ваш сервис поддерживает запрошенное обновление протокола.
`http_request_denied`	Запрос был отклонён политикой до пересылки.	Проверьте политики доступа и конфигурацию вашего сервиса.
`http_protocol_error`	При обмене данными с вашим сервисом произошла ошибка протокола HTTP.	Убедитесь, что ваш сервис отвечает корректным HTTP.
`http_response_incomplete`	Ваша служба вернула неполный HTTP-ответ.	Проверьте сервис на наличие проблем, из-за которых он может разрывать соединения посреди передачи ответа.

Ошибки клиента

Эти ошибки указывают на проблему в настройке VPC Service или в поведении вашего Worker, а не на проблему в самом приватном сервисе.

Код ошибки	Описание	Рекомендуемое исправление
`dns_error` (NXDOMAIN)	Имя хоста, настроенное для вашего VPC Service, отсутствует в DNS.	Убедитесь, что имя хоста в конфигурации вашего VPC Service указано верно и что для него существует DNS-запись.
`connection_read_timeout`	Соединение было установлено, но данные не были получены в течение отведённого времени.	Проверьте код Worker на зависшие или медленные запросы. Убедитесь, что Worker считывает ответ своевременно.
`connection_write_timeout`	Не удалось записать данные в соединение (буферы заполнены).	Проверьте код Worker на медленную обработку данных ответа.
`rate_limited`	Превышен лимит частоты подключений к этому источнику.	Снизьте частоту новых соединений от вашего Worker к этому сервису.

Внутренние ошибки

Эти ошибки указывают на проблему в инфраструктуре Cloudflare, которая не связана с вашей конфигурацией или сервисом источника.

Код ошибки	Описание	Рекомендуемое исправление
`proxy_internal_error`	Внутри прокси Cloudflare произошла внутренняя ошибка.	Это не связано с вашей конфигурацией. Если ошибка повторяется, обратитесь в Поддержка Cloudflare ↗.

Ошибки туннеля

Workers VPC может возвращать ошибки во время выполнения при подключении к приватным службам через Cloudflare Tunnel.

Сообщение об ошибке	Подробности	Рекомендуемые исправления
`Error: ProxyError: dns_error`	Сбой разрешения DNS при попытке подключения к приватному сервису через туннель.	Эта ошибка может возникнуть, если ваш `cloudflared` версия устарела. Убедитесь, что вы используете `cloudflared` версии 2025.7.0 или новее (рекомендуется последняя версия). См. Инструкции по обновлению Cloudflare Tunnel.
`Error: ProxyError: dns_error`	Cloudflare Tunnel можно настроить с `http2` протокол (`TUNNEL_TRANSPORT_PROTOCOL:http2`), которая работает с Cloudflare Zero Trust (см. примечание) трафик, но блокирует разрешение DNS из Workers VPC.	Workers VPC требует Cloudflare Tunnel для подключения с использованием Транспортный протокол QUIC. Убедитесь, что исходящий трафик UDP на порт 7844 разрешён в вашем брандмауэре.
Запросы, выходящие за пределы VPC	Запросы Worker с использованием `.fetch()` с публичным хостом маршрутизируются за пределы VPC к хосту, настроенному для VPC Service.	Убедитесь, что код Worker и VPC Service используют внутреннее имя хоста VPC для бэкенд-сервисов, а не публичное имя хоста.

Ошибки доступа

Если вы не можете просматривать, создавать или привязывать VPC Service и Tunnel в панели управления или через Wrangler, убедитесь, что у вашего пользователя есть необходимые роли.

Workers VPC использует следующие роли аккаунта:

Connectivity Directory Read для просмотра Workers VPC Services и Tunnels.
Connectivity Directory Bind для получения списка, чтения и привязки VPC Services в Workers.
Connectivity Directory Admin для создания, обновления и удаления VPC Services, а также для прямой привязки к туннелям через VPC Network binding.

Описание ролей см. в Роли.

Если ваши роли были недавно обновлены, а команды всё ещё завершаются с ошибкой, обновите аутентификацию Wrangler:

npx wrangler logout
npx wrangler login

Если вы аутентифицируетесь с помощью API-токена (CLOUDFLARE_API_TOKEN), убедитесь, что токен принадлежит пользователю с необходимыми ролями.