Содержание
- 1. «Диагностические команды», которые стоит запустить первыми
- 2. Авторизация и вход
- 3. Использование и лимиты запросов (самое частое)
- 4. Контекст и токены
- 5. Сервер и модель
- 6. Установка, PATH и обновление
- 7. Сеть и прокси
- 8. MCP (подключённые серверы)
- 9. Разрешения и инструменты
- 10. Прочее (thinking / изображения-PDF / IDE)
- 11. Шпаргалка «ошибка → исправление»
- Итоги
- FAQ
Вы работаете в Claude Code, и он внезапно останавливается с ошибкой — «войдите снова», «лимит запросов», «слишком длинный промпт», «MCP не подключается». Разновидностей так много, что гуглить каждую утомительно. Эта статья — практический справочник, который каталогизирует ошибки, чаще всего встречающиеся в Claude Code, с причиной и командой для запуска по каждой из них.
Сразу к сути: для большинства ошибок запуск claude doctor (полная диагностика), /status (ваша текущая авторизация) и /context (разбивка контекста) в первую очередь сузит круг причин. А самые частые сводятся к четырём семействам: ① использование/лимиты запросов, ② переполнение контекста, ③ истёкшая авторизация, ④ сбои подключения MCP. Ниже каждая категория выстроена по схеме «симптом → причина → команда исправления». Добавьте в закладки и переходите к нужному разделу, когда застряли.
Если сомневаетесь — эти 3 команды
— большинство ошибок начинается с изоляции причины
Четыре семейства: ① использование/лимиты запросов ② переполнение контекста ③ истёкшая авторизация ④ сбой подключения MCP.
И незаметно, но «обновление до последней версии» claude update устраняет множество багов.
* Команды и исправления здесь основаны на официальной документации Claude Code (по состоянию на 2026). Claude Code обновляется быстро, и названия команд и формулировки сообщений могут меняться. Проверяйте актуальное состояние через claude doctor и официальную документацию.
1. «Диагностические команды», которые стоит запустить первыми
Прежде чем погружаться в конкретные ошибки, знание диагностических команд, которые помогают изолировать причину, позволяет быстро локализовать большинство проблем.
| Команда | Что показывает / делает |
|---|---|
claude doctor | Полная проверка установки, настроек, серверов MCP, использования контекста |
/status | Текущий активный метод авторизации (Pro / Max / Team / API-ключ) |
/context | Разбивка контекста (системный промпт, история, файлы, инструменты MCP) |
/usage | Текущие лимиты плана и время сброса |
/permissions | Список правил разрешений (allow/deny) и их источники |
/mcp | Статус подключения серверов MCP и количество доступных инструментов |
/feedback | Сообщить о баге в Anthropic вместе с журналом беседы |
2. Авторизация и вход
Семейство «всё работало и вдруг просит войти». Классическая ловушка — API-ключ из переменной окружения переопределяет вашу подписку.
| Симптом | Причина | Исправление |
|---|---|---|
| Not logged in · Please run /login | Для этой сессии нет доступных учётных данных (сохранённый вход, который не удалось обновить, показывается как Login expired · Please run /login) | /login. Если повторяется, проверьте системные часы и блокировку Keychain |
| Invalid API key · Fix external API key | API отклонил ключ из ANTHROPIC_API_KEY или apiKeyHelper (часто устаревший) | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked · Please run /login Please run /login · API Error: 401 OAuth token has expired ... | Выход на всех устройствах / администратор отозвал доступ (revoked); сбой автообновления (expired) | /login. Если повторяется в той же сессии — /logout → /login. Если при каждом запуске — подозревайте рассинхрон часов |
| Your ANTHROPIC_API_KEY belongs to a disabled organization · … API Error: 400 ... This organization has been disabled. | Используется устаревший ANTHROPIC_API_KEY отключённой организации. Если переменной окружения нет, отключена организация вашего /login | Удалите ключ из профиля оболочки (.zshrc и т. п.) → /login → подтвердите через /status. Без переменной окружения — обратитесь в поддержку или войдите с другим аккаунтом |
| 403 Forbidden (after login) | Истёкшая подписка / отсутствует роль / вмешательство прокси | Проверьте подписку и роль в Console. Для прокси задайте HTTPS_PROXY |
Правило: API-ключ из переменной окружения имеет приоритет над входом по подписке. Если вы задали ANTHROPIC_API_KEY для CI-задачи и забыли о нём, ваш личный план Pro/Max будет проигнорирован. Проверить «какие учётные данные активны» через /status в первую очередь — верный ход. Подробный разбор решений по аутентификации и входу (приоритет ANTHROPIC_API_KEY, истечение токена, Keychain и прочее) — в статье причины и способы устранения ошибок аутентификации и входа.
3. Использование и лимиты запросов (самое частое)
Самая частая жалоба в Claude Code. Согласно официальному руководству по расходам (Manage costs effectively), каждый ход Claude Code несёт содержимое файлов, вызовы инструментов и многошаговые рассуждения, поэтому один сеанс отладки может израсходовать больше, чем день общения в чате. Поэтому вы упираетесь в лимиты быстрее, чем кажется.
3 шага, когда вы «упёрлись в лимит»
/usage для лимитов и времени сброса, /status для учётных данных/model для более лёгкой модели, /compact для сжатия истории, отключите неиспользуемые MCP
Примечание: «Server is temporarily limiting requests» — это кратковременное серверное ограничение, а не лимит вашего плана. Просто подождите и повторите.
Не путайте с лимитами плана (сессионными/недельными).
Дополнительно: «API Error: Request rejected (429)» — вы упёрлись в лимит частоты, заданный для вашего API-ключа (или проекта в Amazon Bedrock / Google Cloud); если вы рассчитывали на подписку, проверьте в /status, не затесался ли ANTHROPIC_API_KEY. «Credit balance is too low» — исчерпан предоплаченный баланс Console, либо запросы уходят по API-ключу Console, хотя вы хотели работать по подписке (пополните баланс или проверьте ключ в /status и уберите его). Учтите, что в марте 2026 года пользователи Pro и Max жаловались, что лимиты Claude Code заканчиваются гораздо быстрее ожидаемого, и Anthropic признала, что расследует это в первую очередь (The Register, 31 марта 2026 года). Если это повторяется, обновитесь до последней версии, измеряйте через /usage и при необходимости отправьте /feedback. О системной экономии токенов см. экономию токенов ИИ и экономию токенов в Claude Code. О том, как устроен "usage limit reached" (5-часовое окно и недельное окно) и что делать при достижении лимита, подробно см. отдельный разбор usage limit reached.
4. Контекст и токены
Появляется, когда вы работаете с длинными совещаниями или огромными файлами.
| Симптом | Причина | Исправление |
|---|---|---|
| Prompt is too long | Беседа + файлы превышают окно контекста | /compact (суммаризация), /clear (сброс), /context для просмотра разбивки, отключите неиспользуемые MCP через /mcp |
| Error during compaction: Conversation too long | Недостаточно свободного места для результата сжатия | Дважды Esc, чтобы отмотать несколько ходов, затем /compact. Если всё ещё застряли — /clear |
| Autocompact is thrashing | Огромный вывод сразу после сжатия снова заполняет контекст | Читайте большие файлы по диапазонам строк / /compact keep only <focus> / перенесите в субагента |
Хитрость в том, чтобы никогда не читать огромный файл целиком. Передавайте логи и данные небольшими кусками по диапазонам строк. Понимание идеи окна контекста делает этот класс ошибок гораздо более редким. Подробные причины и способы устранения ошибки Prompt is too long (окно 200K против 1M, использование субагентов) разобраны в отдельной статье.
5. Сервер и модель
| Симптом | Причина | Исправление |
|---|---|---|
| 500 Internal server error | Временный сбой на стороне Anthropic | Проверьте status.claude.com → повторите через 1 мин |
| 529 Overloaded (repeated) | API временно перегружен | Подождите несколько минут. Переключите модель через /model, чтобы распределить нагрузку |
| Request timed out | Нет ответа в течение стандартных 10 мин | Разбейте задачу. На медленном канале повысьте API_TIMEOUT_MS |
| There's an issue with the selected model / Model '…' not found | Неверное имя модели или её нет в вашем плане | /model для повторного выбора. Проверьте устаревшую переменную окружения ANTHROPIC_MODEL |
| Claude Opus is not available with the Claude Pro plan | Выбранной модели нет в вашем плане | /model на доступную. После смены плана — /logout→/login |
Почему 529 Overloaded / 500 — это сбои на стороне сервера и не расходуют вашу квоту, как работает автоматический повтор (до 10 раз) и чем это отличается от 429, подробно разобрано в статье 529 Overloaded / 500: причины и решения.
6. Установка, PATH и обновление
| Симптом | Причина | Исправление |
|---|---|---|
| command not found: claude | Каталог установки не в PATH | Добавьте ~/.local/bin (Win: %USERPROFILE%\.local\bin) в PATH |
| Install fails (HTML error, etc.) | Прокси / региональная блокировка | Homebrew brew install --cask claude-code / WinGet winget install Anthropic.ClaudeCode |
| TLS / SSL certificate verification failed | TLS-инспекция корпоративного прокси / отсутствует CA | Укажите NODE_EXTRA_CA_CERTS=/path/ca.pem. НИКОГДА не задавайте NODE_TLS_REJECT_UNAUTHORIZED=0 |
| Несколько установок Claude Code (несовпадение версий, неожиданное поведение) | Дубликаты из native, npm, Homebrew, WinGet и т. п. | Проверьте через which -a claude (Windows: where.exe claude) и оставьте одну; рекомендуется нативная установка в ~/.local/bin/claude. Например npm uninstall -g @anthropic-ai/claude-code |
| Баги из старой версии | Не обновлено | claude update (главное исправление, устраняющее множество багов) |
| Настольное приложение выдаёт «Can't open this app» | При обновлении пакет MSIX зарегистрировался наполовину (Windows) | Завершите фоновые процессы и нажмите «Восстановить» в параметрах. подробный разбор |
Причины и способы устранения ошибки command not found: claude (PATH, конфликты нескольких установок, права npm, ловушка с неправильной оболочкой в Windows) подробно разобраны в статье как исправить ошибку "command not found" при установке и с PATH.
7. Сеть и прокси
Часто встречается в корпоративных сетях и VPN. Сначала проверьте доступность через curl -I https://api.anthropic.com.
| Симптом | Причина | Исправление |
|---|---|---|
| Unable to connect to API / Connection refused … (ECONNREFUSED) | Нет сети / блокировка VPN / прокси не задан | Задайте HTTPS_PROXY=http://proxy:8080. Попросите IT разрешить api.anthropic.com |
| SSL certificate verification failed (corporate) | Самоподписанный перехватывающий сертификат | Получите CA-бандл у IT и задайте NODE_EXTRA_CA_CERTS |
| 403 host_not_allowed (cloud runs) | Вне белого списка облачного окружения | Установите сетевой доступ в Custom и разрешите целевой домен |
| Connection lost mid-response (до v2.1.227 — Connection closed mid-response) | Соединение установилось, поток пошёл, и затем связь оборвалась | Частичный вывод сохраняется — ответьте continue. При повторах проверьте claude --version и обновитесь |
Подробный разбор настройки proxy, TLS-сертификатов (NODE_EXTRA_CA_CERTS), доменов из allowlist и того, почему NODE_TLS_REJECT_UNAUTHORIZED=0 опасен, смотрите в статье причины и устранение ошибок подключения и proxy. Connection lost mid-response (прежнее название — Connection closed mid-response) — другая проблема, возникающая уже после того, как запрос дошёл: причины и решение, когда ответ обрывается на середине — там разбор по слоям и какие версии что починили.
8. MCP (подключённые серверы)
С этим вы сталкиваетесь, когда начинаете использовать серверы MCP. Сначала проверьте статус через /mcp.
| Симптом | Причина | Исправление |
|---|---|---|
| Server failed to connect / Pending approval | Сервер упал / недоступен / нужна авторизация | /mcp для статуса. stdio: проверьте, что команда существует и исполняема; HTTP: проверьте URL/заголовки авторизации |
| Tool not found | Подключён, но инструменты не доступны / неверное имя | /mcp для подтверждения количества инструментов, claude mcp get <name> для проверки состояния |
| Reconnection attempts exhausted | Сервер HTTP/SSE недоступен после 5 повторов | Убедитесь, что сервер работает, выполните ручное переподключение в /mcp. Для stdio перезапустите claude |
| MCP server timeout | Запуск не укладывается в MCP_TIMEOUT (по умолчанию 30 с) | Увеличьте в мс, например MCP_TIMEOUT=60000 claude. "timeout" в .mcp.json — это лимит выполнения каждого инструмента, а не ожидание запуска |
Подробный разбор по статусам подключения MCP —failed, needs authentication, pending— (включая обёртку npx через cmd /c в Windows) смотрите в статье как исправить ошибки подключения MCP.
9. Разрешения и инструменты
Семейство «спросил разрешение даже в режиме обхода». Два ключевых момента: официальная документация перечисляет действия, которые запрашивают подтверждение даже в режиме bypass, и правила deny блокируют в любом режиме, включая bypass (правила allow в bypass не действуют; см. Choose a permission mode в официальной документации).
| Симптом | Причина | Исправление |
|---|---|---|
| Спрашивает разрешение даже в режиме bypass | Явные правила ask, инструменты, требующие действия пользователя, например AskUserQuestion, и rm / rmdir для критического пути — корня, домашней папки или рабочего каталога (документация называет это circuit breaker) — запрашивают подтверждение и в bypass. Запись в защищённые пути вроде .git и .claude в bypass подтверждения не требует | Проверьте и скорректируйте правила ask в /permissions. Правила deny блокируют без запроса |
| Tool execution denied by PreToolUse hook | Хук заблокировал её с кодом выхода 2 | Проверьте хук в .claude/settings.json. Смотрите вывод через claude --debug |
О том, почему bypass всё равно останавливается, см. почему он спрашивает разрешение даже в режиме обхода; о безопасном проектировании разрешений см. режимы разрешений и безопасность.
10. Прочее (thinking / изображения-PDF / IDE)
- thinking blocks cannot be modified (400): известный баг, когда блоки расширенного мышления повреждаются в истории. Дважды Esc → /rewind, иначе новая сессия и
claude update. Подробности: ошибка 400 thinking blocks. - court / показывается сырой тег <invoke>, и инструмент не выполняется: известный баг, когда управляющий тег вызова инструмента генерируется в сломанном виде. Если не сработало дважды, начните новую сессию (/clear). Подробности: разбор ошибки утечки тега court / invoke.
- Could not check the pull request status: проблема подключения к GitHub (часто авторизация
gh). Начните сgh auth status. Подробности: ошибка проверки статуса PR. - Image was too large / PDF too large: изображения свыше 8000px по длинной стороне (2000px, когда в контексте много изображений), PDF свыше 100 страниц / 20 МБ отклоняются. Дважды Esc, чтобы удалить вложение; измените размер или читайте по диапазонам строк. Ссылайтесь на большие файлы по пути, а не вставляйте их.
- Расширение VS Code не подключается: убедитесь, что
claude --versionработает в терминале VS Code. Проверьте PATH, перезапустите VS Code, переустановите расширение.
11. Шпаргалка «ошибка → исправление»
| Когда это происходит | Попробуйте сначала это |
|---|---|
| Причина неизвестна / общий случай | claude doctor → /status → /context |
| Внезапно просит войти | /status → (если устаревший ключ) unset ANTHROPIC_API_KEY → /login |
| Упёрлись в лимит запросов | /usage → /model легче → /compact → подождите |
| Prompt is too long | /compact → /clear → читайте большие файлы по диапазонам строк |
| 500/529/тайм-аут | Проверьте status.claude.com → немного подождите → /model |
| command not found: claude | Добавьте ~/.local/bin в PATH |
| Не подключается (корпоративная сеть) | curl -I https://api.anthropic.com → HTTPS_PROXY/NODE_EXTRA_CA_CERTS |
| MCP не подключается | /mcp → проверьте URL/права/команду → MCP_TIMEOUT |
| Запрашивает даже в bypass | /permissions для проверки правил ask (удаление критического пути запрашивает подтверждение даже в bypass) |
| Просто хочу, чтобы заработало | claude update (последняя версия исправляет многое) |
Итоги
У Claude Code много ошибок, но первый ход — изолировать причину тремя командами: claude doctor / /status / /context — и это снова сдвигает с места большинство проблем. Самые частые — это четыре семейства: использование/лимиты запросов, переполнение контекста, истёкшая авторизация, сбой подключения MCP — с /usage, /compact, /login и /mcp в качестве первоочередных исправлений.
А легко упускаемый, но сильнейший ход — поддержание актуальности через claude update. Claude Code обновляется быстро, и прошлые баги (например, 400 у thinking blocks) часто исчезают просто за счёт повышения версии. «Застряли — сначала три диагностические команды; если не исправилось — обновитесь до последней версии». Держитесь этого шаблона, и вы перестанете терять время на ошибках.
Если это не ошибка, а вас смущает, что поведение кажется слишком тяжёлым или медленным, стоит пересмотреть настройку усилия (effort) в Claude Code — это позволяет отрегулировать баланс между глубиной рассуждений и расходом токенов. По теме: ошибка 400 thinking blocks, ошибка проверки статуса PR, экономия токенов в Claude Code, почему он спрашивает разрешение в режиме обхода, что такое MCP и The model returned no content — причины и решение.
FAQ
Q. Появилась ошибка — что делать в первую очередь?
A. Запустите claude doctor. Он проверяет установку, настройки, MCP и контекст за один раз. Затем посмотрите /status (текущая авторизация) и /context (что съедает контекст), и обычно вы сможете понять, в чём проблема — в авторизации, контексте или подключении.
Q. Я быстро упираюсь в лимиты запросов. Что помогает?
A. Каждый ход Claude Code несёт содержимое файлов и вызовы инструментов, и официальная документация отмечает, что один сеанс отладки может израсходовать больше, чем день общения в чате, поэтому вы упираетесь в них раньше, чем ожидаете. Проверьте лимиты и время сброса через /usage, переключитесь на более лёгкую модель через /model, сожмите историю через /compact и отключите неиспользуемые MCP. Если этого недостаточно, рассмотрите более высокий план (Max и т. п.) или дополнительные кредиты.
Q. Пишет «Invalid API key», хотя ключ должен быть верным.
A. Классическая причина — устаревшая переменная окружения ANTHROPIC_API_KEY, переопределяющая вашу подписку. Проверьте через env | grep ANTHROPIC, выполните unset ANTHROPIC_API_KEY (удалите её также из профиля оболочки), затем /login и подтвердите через /status.
Q. Не подключается в моей корпоративной сети.
A. Сначала проверьте доступность через curl -I https://api.anthropic.com. Для прокси задайте HTTPS_PROXY; для TLS-инспекции укажите NODE_EXTRA_CA_CERTS на CA-сертификат. Не используйте NODE_TLS_REJECT_UNAUTHORIZED=0 — это опасно. Правильный путь — попросить IT разрешить api.anthropic.com.
Q. Ничего из того, что я пробую, не работает — последнее средство?
A. Обновитесь до последней версии через claude update. Claude Code обновляется быстро, и известные баги часто исчезают просто за счёт повышения версии. Если по-прежнему не работает, отправьте отчёт через /feedback (включает журнал беседы) в Anthropic.
