Занимаясь ИИ-программированием, вы обязательно встретите ошибки. Руки замирают в момент, когда появляется красный текст — именно это время главный враг продуктивности. Но не волнуйтесь. Ошибки, с которыми сталкиваешься в Claude Code и других ИИ-инструментах, почти все — повторение заданных шаблонов. Стоит научиться различать тип — и решение определяется почти механически. Эта глава — карта диагностики (сортировки) неполадок, которую открываешь первой, когда застрял.
Стать тем, кто «не замирает от ошибок»
🧭 Сначала одна сводная статья. Общая сводка частых ошибок собрана в «Claude Code — частые ошибки и способы устранения». Эта глава — карта, обозревающая каждую категорию, а отдельные статьи по ссылкам содержат конкретные примеры сообщений и шаги. Добавьте в закладки и, застряв, идите отсюда.
Ошибки различают «по типу»
Первый шаг к решению — различить, «к какому типу относится эта ошибка». Если слой причины другой, то и место починки другое. Прежде чем вчитываться в детальное сообщение, сначала отнесите ошибку к одной из 6 категорий ниже. В момент отнесения решение определяется на 80%.
Вообще не запускается, нет команды. Проблема на входе. ↓подробнее
Не удаётся войти, слетает авторизация. Связь с учётной записью. ↓подробнее
Нет связи, перегрузка сервера. Проблема маршрута и стороны сервера. ↓подробнее
Достигнут предел, недоступное время. Проблема тарифа и объёма использования. ↓подробнее
Слишком длинно, перегружено. Проблема объёма переданной информации. ↓подробнее
Сбой расширения или вызова инструмента. Проблема сопутствующих функций. ↓подробнее
💡 Приём распознавания. По одному ключевому слову в тексте ошибки можно прикинуть, куда бить. command not found→①, authentication/login→②, connection/network/529→③, usage limit→④, too long→⑤, MCP/tool→⑥. Прежде чем читать сообщение целиком, сначала найдите это слово.
① Установка и запуск — команда не найдена
Первое препятствие — «вообще не запускается». Установка сорвалась на полпути, или не прописан путь (PATH), и на введённую команду нет реакции. Застрять здесь — значит не двинуться дальше, поэтому спокойно проверьте вход.
Симптом: вводишь claude — отвечает «такой команды нет».
Причина: к месту установки не прописан PATH, не перечитана оболочка, или сама установка не завершена.
Решение: заново открыть терминал / проверить PATH / переустановить. Пробуя по порядку, чаще всего выбираешься.
Симптом: установка останавливается на ошибке / отклоняется по правам (permission).
Причина: старая версия Node.js, нехватка прав, сбой загрузки пакета по сети.
Решение: обновить базовое окружение (Node и т.п.), пересмотреть права администратора и способ установки. В корпоративной сети заподозрите и прокси.
🔧 Подробные шаги здесь. Разделение причин сбоя установки и command not found и конкретные способы починки собраны в «Как исправить command not found / ошибку установки». Застряли на установке — кратчайший путь — заново поставить строго по шагам главы 2 «Начать с Claude Code».
② Вход и аутентификация — не проходит проверка
Запуск идёт, но отклоняет на входе или аутентификации. Проявляется как «не удаётся браузерная аутентификация» или «попользовался — и внезапно разлогинило». Состояние, когда «рукопожатие» между учётной записью и инструментом рассинхронизировано.
Симптом: не пройти дальше экрана входа / отклоняет с ошибкой аутентификации / не открывается браузер для проверки.
Причина: истёк или повреждён токен аутентификации, сбой перенаправления, путаница с тарифом или нужным аккаунтом, расхождение времени.
Решение: выйти и войти заново / очистить сохранённые данные аутентификации и пройти проверку снова / убедиться, что аккаунт верный.
То, что выглядит как «ошибка аутентификации», на деле может быть просто несовпадением тарифа или объекта договора.
Тем, кто пользуется несколькими аккаунтами, сначала стоит проверить аккаунт, под которым вошли, и вид тарифа. Смешение рабочего и личного — типичная ловушка.
🔑 Подробные шаги здесь. Шаги повторного входа и переполучения токена, когда аутентификация не проходит, есть в «Как справиться с ошибкой входа / аутентификации». Чаще всего решается повторным входом, но если не помогло — заподозрите и сторону сети (③).
③ Соединение и сеть — не подключается, перегрузка
Здесь причина делится на две — «ваша сторона» и «сторона сервера», поэтому важна диагностика. Ваш канал или прокси перекрывают связь, или сервер временно перегружен? В первом случае вы чините сами, во втором базовая тактика — ждать или облегчать нагрузку.
Симптом: не подключается, тайм-аут, связь обрывается на полпути.
Причина: сбои канала, блокировка корпоративным прокси или брандмауэром, VPN, проблемы с сертификатом или DNS.
Решение: попробовать другой канал / отключить VPN / пересмотреть настройки прокси. В корпоративной сети уточните у администратора список разрешённого.
Симптом: возвращается overloaded или 5xx. Ваши настройки верны, а всё равно сбой.
Причина: временная высокая нагрузка или сбой на стороне сервера. Не из-за вашего кода или настроек.
Решение: немного подождать и повторить / избегать часов пик / проверить сведения о сбое (страница статуса).
⚠️ Ориентир для диагностики. Если другие сайты и сервисы в норме, а падает только ИИ-инструмент — велика вероятность стороны сервера (529/500), и решение — «ждать». Если и другая связь нестабильна — дело в вашей стороне (канал, прокси, VPN). Подробнее — «Ошибки соединения, сети и прокси» и «Что значат ошибки 529 overloaded / 500 и что делать».
④ Лимиты использования — достигнут предел
Это не ошибка, а уведомление «достигнут лимит, сейчас пользоваться нельзя». У каждого тарифа есть предел объёма за определённый промежуток и за неделю, и при его достижении работа временно останавливается. Это не поломка, поэтому правильно не чинить, а подстраивать использование и тариф.
Симптом: отображается «достигнут лимит использования», и до определённого времени пользоваться нельзя.
Причина: достигнут предел объёма тарифа. Если гонять крупные задачи или длинные разговоры за короткое время, доходишь быстрее.
Решение: подождать до сброса / разбить разговор и пользоваться легче / при необходимости пересмотреть тариф.
Симптом: достигаешь предела посреди недели / кажется, что сброс наступает раньше или позже, чем думал.
Причина: недельная квота порой устроена не по календарной неделе — например, отсчитывается от первого использования.
Решение: правильно понять способ отсчёта сброса и планомерно распределять «тяжёлые» по расходу работы.
📊 Лимитов почти можно избежать «управлением». Смысл лимита и подход к времени ожидания — в «Что делать при достижении лимита использования», способ отсчёта недельного сброса — в «Как недельный лимит сбрасывается раньше». А само использование, реже упирающееся в лимит, сведено в главе 7 «Расходы и эффективность».
⑤ Ввод и контекст — слишком длинно
У объёма информации (контекста), который ИИ обрабатывает за раз, есть предел. Если разговор затянулся или вы целиком передали огромный файл, вас отклонят с «ввод слишком длинный». Это признак перегрузки, поэтому решение — уменьшить объём передаваемого, разбить.
Симптом: появляется «ввод слишком длинный», и указание не выполняется.
Причина: накопление истории разговора, чтение огромного файла или множества файлов, слишком длинный вставленный лог.
Решение: упорядочить или обобщить разговор / начать новый / передать только нужный фрагмент / разбить задачу на мелкое.
Симптом: ошибка в обработке, связанной с рассуждением (thinking), и ответ прерывается.
Причина: рассогласование состояния разговора или внутреннее расхождение, связанное с историей. Легче случается в длинных разговорах.
Решение: начать разговор заново / разделить соответствующий обмен. Чаще всего снимается обновлением.
✂️ «Длинно» предотвращается проектированием. Конкретные способы сократить — в «Как справиться с prompt is too long», неполадки вокруг thinking — в «Как справиться с ошибкой thinking block». Коренная мера — дробить задачу на мелкое, а это напрямую связано со способом указания из главы 4 «Грамотно просить».
⑥ MCP и инструменты — расширение работает неправильно
При MCP (связке с внешними инструментами) и вызове инструментов бывает так, что сам Claude Code в порядке, но сбоит только сопутствующее расширение. Приём — рассматривать это отдельно от ошибок ядра. Сначала проверьте, «воспроизводится ли, если убрать расширение», — и диагностика причины резко продвинется.
Симптом: не подключиться к MCP-серверу / связанный инструмент не появляется в списке или не реагирует.
Причина: ошибка в записи файла настроек, сбой запуска сервера, нехватка путей или зависимостей, изъяны в данных аутентификации.
Решение: пересмотреть настройки / проверить запуск сервера по отдельности / раз убрать и продиагностировать, работает ли только ядро.
Симптом: вызов инструмента срывается / застревает при передаче результата вызова.
Причина: рассогласование определения инструмента или аргументов, сдвиг состояния разговора, временный сбой на стороне связанного сервиса.
Решение: перезапустить разговор / временно отключить нужный инструмент для диагностики / проверить состояние связанного сервиса.
Симптом: ошибка в статус-проверках вокруг PR (pull request).
Причина: часто замешаны настройки или права связанного CI и проверок, состояние на стороне внешнего сервиса.
Решение: проверить настройки и права стороны проверок / перезапустить / проверить состояние внешнего сервиса.
🧩 Расширения — «убрать и продиагностировать». Как чинить подключение MCP — в «Как справиться с ошибкой подключения MCP-сервера», неполадки вызова инструментов — в «Как справиться с ошибкой вызова инструмента», всё, что связано с PR-проверками, — в «Как справиться с ошибкой статус-проверки PR». Само использование расширений разобрано в главе 6 «Использовать расширения».
Как выбраться из тупика — универсальные 5 ходов
Даже когда причину сходу не определить, есть «универсальный ход», который стоит попробовать первым. Многие ошибки исчезают от одного лишь обновления состояния или облегчения нагрузки. Когда по категориям выше не удаётся прицелиться, пробуйте эти 5 сверху вниз.
Закройте и заново откройте инструмент и терминал. Временные сбои состояния по большей части исчезают уже от этого. Первый ход, который стоит заподозрить.
Длинный разговор — рассадник рассогласований. Начните новый или облегчитесь, обобщив и упорядочив историю (в духе /compact). Помогает при ⑤.
Не просите много за раз, а дробите задачу на маленькие шаги. Ошибки от «слишком длинно / слишком тяжело» так избегаются в корне.
529/500 и перегрузку решает время. Подождите несколько минут и повторите. Проверьте и сведения о сбое на странице статуса. Помогает при ③④.
Если совсем непонятно — передайте текст ошибки целиком ИИ или в поиск. Сверив со сводной статьёй этой главы, чаще всего попадёте на известный шаблон.
🧯 Не паниковать — лучшее лекарство. Ошибка — не сигнал «сломалось», а подсказка «почини вот здесь». Различить категорию, попробовать 5 ходов выше, а если всё равно не вышло — к отдельным статьям. Стоит усвоить этот поток — и красный текст больше не страшен.
- Ошибки сначала разбивают на 6 категорий (установка, аутентификация, соединение, лимиты, контекст, MCP/инструменты). По одному ключевому слову можно прицелиться.
- У каждой категории симптом → причина → решение почти шаблонны. Сторона сервера (529/500) — «ждать», слишком длинно — «разбить, упорядочить».
- Даже без ясной причины универсальные 5 ходов (перезапуск, перезапуск разговора, разбить на мелкое, подождать и повторить, передать текст ошибки как есть) выведут из большинства ситуаций.
- Конкретные шаги — в сводной статье и отдельных материалах. Управление лимитами — в главе 7, расширения — в главе 6.
Когда понятно, как ладить с ошибками, ИИ-программирование резко идёт вперёд. Следующий черёд — расширять сами возможности Claude Code. В следующей главе 6 «Использовать расширения» с помощью hooks, plugins, subagents и MCP сделаем напарника ещё сильнее.