Ошибки Claude Code: 10 частых + причина и решение

Ошибки Claude Code делятся на четыре кучки: не поставился, не пустил, кончились лимиты, не понял задачу. Ниже — десять сообщений, которые встречаются чаще всего, с причиной и порядком действий. Общее правило перед всем списком: сначала посмотрите на версию — claude --version, — потому что часть проблем чинится обновлением, а не разбирательством.

1. claude: command not found

Что происходит. Пакет установлен, а команда не находится.

Причина. Каталог с исполняемым файлом не попал в PATH. Классика для установки через npm с правами обычного пользователя.

Что делать. Проверить, куда npm кладёт бинарники (npm bin -g), и добавить этот путь в PATH профиля оболочки. Перезапустить терминал — не вкладку, а именно оболочку. Подробный разбор для трёх систем — в инструкции по установке.

На Windows отдельная ловушка: команда, поставленная внутри WSL, не видна из PowerShell и наоборот. Это две разные среды.

2. Not logged in · Please run /login

Что происходит. Сессия открывается, но агент просит войти.

Причина. Токен входа истёк либо конфигурация не читается — например, вы запускаетесь от другого пользователя, чем при первом входе.

Что делать. Выполнить /login и пройти авторизацию в браузере. Если сообщение возвращается после каждого запуска, проверьте права на каталог конфигурации: агент должен уметь в него писать.

В расширении для VS Code это же сообщение появляется, когда редактор не унаследовал переменные окружения оболочки — что с этим делать.

3. Invalid API key

Что происходит. Ключ введён, но не принимается.

Причина. Три варианта, по убыванию частоты: ключ скопирован с пробелом или переносом строки; ключ от другого аккаунта или отозван; в окружении лежит старый ANTHROPIC_API_KEY, который перекрывает новый.

Что делать. Проверить, что реально лежит в переменной окружения, а не что вы туда клали. Ключ должен начинаться с sk-ant-. Как завести новый — инструкция по ключу.

ОсторожноЕсли ключ хоть раз попадал в репозиторий, историю сообщений или скриншот — отзывайте и заводите новый. Утёкший ключ тратят чужие люди, и счёт приходит вам.

4. Credit balance is too low

Что происходит. Ключ верный, но запрос не проходит.

Причина. На балансе API нет средств. Это не то же самое, что подписка: оплаченная подписка Pro или Max не пополняет баланс API, и наоборот.

Что делать. Определиться, чем вы платите. Работаете каждый день — подписка; заходите изредка или автоматизируете — API с пополненным балансом. Разбор, что выгоднее.

5. Лимит подписки исчерпан

Что происходит. Агент сообщает, что лимит использования достигнут, и предлагает подождать.

Причина. Лимиты Pro считаются окнами и обновляются каждые несколько часов. Упереться в них на плотной работе с большим проектом — нормально.

Что делать. Три варианта: подождать окно, перейти на Max, либо на время переключиться на API-ключ. Четвёртый, недооценённый: уменьшить расход — держать в проекте меньше лишнего и не начинать каждую задачу с нуля. Чем длиннее одна сессия по одному проекту, тем больше работает кеширование.

Проверить своё положение можно командой /usage.

6. Prompt is too long / контекст переполнен

Что происходит. Агент отказывается принимать запрос или начинает забывать начало разговора.

Причина. Проект вместе с историей разговора не помещается в контекстное окно. Обычно это не размер вашего вопроса, а накопившаяся сессия и объёмные ответы инструментов.

Что делать. Начать новую сессию: /clear сбрасывает контекст, /compact сжимает его, сохраняя суть. Дальше — работать задачами покороче и не держать в проекте каталоги, которые агенту не нужны. Если контекст переполняется постоянно, посмотрите разбор проблемы целиком — механика у всех агентов одинаковая.

7. MCP-сервер подключён, но инструментов нет

Что происходит. Сервер числится в списке, а вызывать нечего.

Причина. Чаще всего сервер падает при старте, и клиент видит пустой список. Вторая по частоте причина — посторонний вывод в stdout: любая лишняя строка ломает протокол.

Что делать. Запустить сервер отдельно, командой из его документации, без агента. Падает сам по себе — дело не в конфигурации Claude Code. Дальше — npx @modelcontextprotocol/inspector, он показывает, что сервер объявляет. Полный порядок проверки — подключение MCP и как устроен свой сервер.

8. Агент отказывается править файл

Что происходит. Запрос понят, но правка не выполняется.

Причина. Файл вне рабочего каталога сессии, права на запись отсутствуют, либо текущий режим разрешений это запрещает.

Что делать. Проверить, из какой папки запущена сессия: агент работает в ней и её подпапках, а не в системе целиком. Проверить режим разрешений — в расширении он показан внизу окна ввода, в терминале переключается на ходу. Расширять права стоит осознанно, а не кнопкой «разрешить всё».

9. Агент «не видит» изменений, которые вы внесли руками

Что происходит. Вы поправили файл в редакторе, а агент рассуждает о старой версии.

Причина. Он опирается на то, что прочитал раньше в этой сессии.

Что делать. Сказать прямо: «я поправил файл X вручную, перечитай его». Это работает надёжнее, чем надеяться, что он заметит. В расширении для VS Code этой проблемы меньше — там правка в окне сравнения учитывается автоматически.

10. Сделал не то, что просили

Формально не ошибка, а самая частая жалоба. Три причины, в порядке частоты:

Задача поставлена без границ. «Почини тесты» — агент починит все, включая те, которые вы трогать не хотели. Называйте, что делать, где и чего не трогать.

В проекте нет правил. Без CLAUDE.md агент угадывает соглашения заново каждый раз. Команда /init в новом проекте — минута, которая снимает половину таких претензий.

Спор в одной сессии до победы. Три неудачных круга — сигнал, что дело в формулировке, а не в упрямстве агента. Начните заново с другой постановкой: дешевле и по времени, и по токенам.

Общий порядок разбора

Когда непонятно, с чего начать:

1. Версия — claude --version, обновиться. Часть ошибок уже исправлена.
2. Что именно сломалось — вход, лимиты, инструменты или понимание задачи. Это четыре разные истории.
3. Воспроизвести на чистом проекте. Пустая папка, простая задача. Работает там — дело в вашем проекте, не в инструменте.
4. Отдать ошибку самому агенту. Текст целиком плюс что вы делали. На своих же сообщениях он разбирается неплохо.

Коротко о главном

• Команда не находится — это PATH, а на Windows ещё и путаница между WSL и PowerShell.
• Подписка и баланс API — разные вещи; оплата одного не открывает другое.
• Контекст переполняется от накопленной сессии, а не от длины вопроса: /clear и /compact.
• Пустой список инструментов MCP — почти всегда упавший сервер или вывод в stdout.
• Агент правит только в каталоге, из которого запущен.
• «Сделал не то» лечится границами в постановке и файлом правил проекта, а не спором.

Дальше: установка и первый запуск, первый день работы, команды.