Как исправить ошибку HTTP 502 в Shopify CLI

During the initial sync the CLI asks Shopify’s Admin GraphQL API for the list of files that belong to the theme. A 502 = Bad Gateway means the request reached Shopify’s edge but the backend couldn’t deliver a proper response.
The fact that only your machine sees it points to something in your local environment or network that interferes with that call – not a store‑wide outage. Below is a step‑by‑step checklist that covers the most common culprits and shows how to fix them.

Содержание

• 1. Проверка статуса Shopify
• 2. Сетевые настройки и прокси
• 3. Параметры CLI и конфигурация
• 4. Кеши и DNS‑таблица
• 5. Перезапуск и повторная аутентификация
• 6. Логи и диагностика

1. Проверка статуса Shopify

Прежде чем менять что‑то на своей машине, убедитесь, что сам API работает.
Посетите страницу статуса: https://status.shopify.com/
Если там указано, что GraphQL‑конечные точки находятся в нормальном состоянии, можно переходить к локальной проверке.

Tip: Иногда Shopify временно ограничивает доступ по IP‑адресу. Если ваш IP находится в списке «запрещённых», именно тогда вы можете получить 502.

2. Сетевые настройки и прокси

2.1. Отключите VPN / корпоративный прокси

• Если вы подключены к VPN, отключите его и попробуйте снова.
• На многих предприятиях используется HTTP‑прокси, который перехватывает HTTPS‑трафик и может вернуть 502, если прокси не понимает запросы GraphQL.

Отключение прокси

bash

export HTTPS_PROXY=
export HTTP_PROXY=

2.2. Проверка переменных окружения

Если переменные HTTPS_PROXY или HTTP_PROXY заданы в системе, CLI может пытаться использовать их. Убедитесь, что они пусты или корректные.

Справка – как проверить переменные в macOS/Linux: env | grep -i proxy

2.3. Попробуйте другой DNS

Иногда провайдеры меняют IP‑адреса и кэшованный DNS‑запись может указывать на устаревший сервер. Попробуйте:

# flush DNS cache
sudo killall -HUP mDNSResponder     # macOS
sudo systemd-resolve --flush-caches # Linux

После этого выполните shopify theme sync ещё раз.

3. Параметры CLI и конфигурация

3.1. Проверка версии CLI

shopify version

Убедитесь, что версия ≥ 2.0.0. Если вы используете старую 1.x‑версию, она может посылать устаревшие GraphQL‑запросы.

3.2. Пересоздайте конфигурацию

При ошибке 502 может быть повреждён токен‑файл. Удалите его и выполните вход заново:

rm ~/.config/shopify-cli/config.yml
shopify logout
shopify login
shopify theme sync

Почему это работает?
CLI хранит токен в ~/.config/shopify-cli/config.yml. Если он повреждён, API может вернуть неожиданные ошибки, в том числе 502.

3.3. Проверка переменной SHOPIFY_API_VERSION

CLI автоматически использует последнюю версию API, но если у вас явно выставлена устаревшая версия, она может вызвать проблемы. Убедитесь, что она не указана в .shopify-cli.yml или в переменной окружения.

cat ~/.config/shopify-cli/config.yml | grep -i "api_version"

Если там 2023-04 (или старше), обновите до 2024-01 либо удалите строку, чтобы CLI автоматически использовал текущую.

4. Кеши и DNS‑таблица

4.1. Очистка кэша npm

Иногда старые пакеты могут конфликтовать с новыми зависимостями Shopify CLI:

npm cache clean --force

4.2. Перезапуск Node и CLI

После очистки кэша перезапустите терминал. Это гарантирует, что переменные окружения обновятся.

5. Перезапуск и повторная аутентификация

1. Выход
   bash

   shopify logout
   

2. Очистка кэша CLI
   bash

   shopify cache clean
   

3. Вход
   bash

   shopify login
   

4. Синхронизация
   bash

   shopify theme sync
   

Если после этого ошибка исчезла, значит, проблема была в устаревшем токене или кэше.

6. Логи и диагностика

6.1. Включите подробный режим

shopify theme sync --verbose

В выводе ищите строку, содержащую https://admin.shopify.com/api/graphql.
Если там виден запрос с заголовками, убедитесь, что в них присутствует Authorization: Bearer <token> и Content-Type: application/json.

6.2. Запрос через curl

Попробуйте выполнить тот же запрос вручную, чтобы убедиться, что сеть работает:

curl -X POST https://admin.shopify.com/api/2024-01/graphql.json \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: <ваш_токен>" \
  -d '{"query":"{ shop { name } }"}'

Если вы получите 502 от curl, значит проблема действительно в сети. Если curl возвращает 200, то ошибка специфична для Shopify CLI.

6.3. Проверка логов Shopify

Если вы являетесь администратором магазина, перейдите в Shopify Admin → Settings → API → Admin API → Logs. Там могут быть записи о запросах, которые вернули 502, и указание причины.

Итоги

Если после выполнения всех пунктов проблема остаётся, посмотрите открытые вопросы в репозитории GitHub Shopify CLI: https://github.com/Shopify/shopify-cli/issues. Часто там уже есть решения или вы можете открыть новый issue с подробным логом.

Надеюсь, один из этих шагов поможет вам справиться с 502 и вернуть синхронизацию в рабочее состояние.