troubleshooting

Когда не работает

Эта страница нужна, когда max показал ошибку или сделал не то, что вы ждали. Найдите сообщение, которое видите, или его код возврата — и страница скажет, что он значит и что делать дальше. Чаще всего хватает одной команды.

Слова, которые здесь встречаются:

• Код возврата — число, которым команда заканчивается: 0 — команда завершилась; у пакетного чтения проверьте полноту, любое другое число называет вид сбоя. Его читают скрипты и ИИ-агенты; таблица ниже ведёт от каждого кода к разделу.
• max personal doctor проверяет установку, не подключаясь к MAX. Запускайте его первым.
• --trace показывает каждый запрос к MAX по ходу работы, без текста сообщений (диагностика).

В выводе --json ошибка, завершающая команду, — одна строка в stderr, {"error":{"code":"…","message":"…"}}, и код возврата говорит то же, что code. Все коды есть и в справочнике кодов возврата.

По коду возврата

Код	Имя	Что обычно значит	Где
1	internal_error	опечатка в названии команды или сбой в самом max	не тот профиль, сообщить
2	validation_error	значение или сочетание опций, которых max не принимает; имя подходит нескольким чатам	значения, несколько чатов
3	configuration_error	ошибка в config.json, или локальную копию записала более новая версия	настройки, локальная копия
4	authentication_error	нет входа, сессию завершили, или ключница недоступна	нет сессии, токен не читается
5	permission_error	permissions профиля запретили действие	не разрешено
6	not_found	нет такого чата, сообщения или человека; в локальной копии ещё пусто	нет чата, ничего не сохранено
7	confirmation_required	чата нет в списке получателей, или действие ждёт подтверждения, а ответить некому	список получателей, спрашивает
8	rate_limited	лимит профиля в час, или MAX просит подождать	лимит в час, слишком много входов
9	timeout	MAX не ответил вовремя, или --timeout остановил команду	команда висит
10	network_error	MAX недоступен отсюда	команда висит
11	provider_error	MAX отказал в запросе	сообщить
12	provider_unavailable	сбой на стороне MAX	сообщить
13	invalid_response	ответ, который max не смог прочитать	неожиданный ответ
14	outcome_unknown	связь оборвалась после отправки, или у max sales bot шлюз ответил 502, 503 или 504 на изменение: сообщение могло уйти	исход неизвестен
130	cancelled	нажали Ctrl-C или ответили «нет» на вопрос	Ctrl-C

Сначала — max doctor

max personal doctor

Он никуда не подключается и показывает то, от чего зависит любая команда: версию и среду, файл настроек, токен и запись в ключнице (и не сдвинули ли её переменные MAX_*_DIR), общее хранилище, каталог запусков и паузу входа, если она есть. Он отвечает и тогда, когда всё остальное сломано — именно тогда его и запускают. Профиль без сессии не ошибка, а строка в ответе; код возврата остаётся 0. Токен не печатается никогда — только «есть» и «откуда».

max personal doctor --online

--online ещё и входит в MAX один раз, читает один чат и запускает сервер MCP. Ничего не отправляет и ничего не отмечает прочитанным. Вход засчитывается в лимит MAX на входы, поэтому при ошибке он не повторяется (что показывает max personal doctor).

Установка

max не находится после установки

Установка прошла, а терминал отвечает, что команды max нет. Узнать причину можно без неё:

npx @wirecat/max-cli doctor

Строка max on PATH покажет, найдена ли команда, а заметка ниже — что сделать.

Windows. npm кладёт команду в %APPDATA%\npm. Если этого каталога нет в PATH, max personal doctor, запущенный после установки, напечатает две строки PowerShell: первая чинит текущее окно, вторая — все новые. Проверить вручную:

npm prefix -g
$env:Path -split ';'

Первая команда называет каталог, вторая — что сейчас в PATH. Если каталог в списке есть, а max всё равно не находится, закройте и откройте терминал: окно, открытое до установки Node, не видит новый PATH.

PowerShell отвечает «running scripts is disabled on this system». npm кладёт рядом max.ps1 (и npx.ps1), а PowerShell по умолчанию запрещает скрипты. Либо запускайте max.cmd и npx.cmd — они работают всегда (npx.cmd @wirecat/max-cli doctor), — либо разрешите скрипты для своей учётной записи:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Linux и macOS. Каталог команд npm — $(npm prefix -g)/bin. max personal doctor напечатает строку export PATH=…; её нужно дописать в ~/.zshrc или ~/.bashrc.

На PATH другой max. Если раньше в PATH стоит чужая программа с тем же именем, max personal doctor назовёт её путь. Вызывайте нашу по полному пути или поставьте её каталог раньше.

npx @wirecat/max-cli ставит не ту версию

npx кэширует. Явная версия обходит кэш:

npx @wirecat/max-cli@latest --version

Вход и профили

«no session for profile "default"»

{"error":{"code":"authentication_error","message":"no session for profile \"default\" — run `max personal setup` in a local terminal; agents: read `max skill show`"}}

Код возврата 4. Токена для этого профиля нет — либо не входили, либо вошли в другой профиль, либо вошли с другими переменными каталогов.

max personal setup                  # первый запуск
max personal chats list    # или назвать профиль, в который входили

Прерванный первый запуск можно продолжить повторным max personal setup. Истёкший токен требует явного повторного входа: max personal session start qr. Агент перед входом читает max skill show.

⚠ Самая частая причина, когда токен точно есть: MAX_CONFIG_DIR задана в одном окне терминала и не задана в другом. Эти переменные переносят и запись в ключнице, поэтому сессия, сохранённая с ними, невидима без них. Проверьте env | grep MAX_.

«profile "shop" is a bot»

{"error":{"code":"authentication_error","message":"profile \"shop\" is a bot — its commands are `max shop bot …`; `max shop session start` would add a personal account to it"}}

Личная команда запущена на профиле бота. Команды бота начинаются с bot:

max shop bot chats list
max shop bot messages list -100

max shop session start не нужен, если вы не хотите держать под этим именем ещё и личный аккаунт. max shop doctor покажет, что у профиля есть.

«no token found for profile "default", although it has logged in on this machine»

Код возврата 4. Профиль на этом компьютере уже входил, но токен не читается. Почти всегда это хранилище паролей, до которого max не достучался: команда запущена из cron, по ssh или из другого окружения без XDG_RUNTIME_DIR. Не входите заново — это добавит в аккаунт ещё одно устройство, а в следующий раз из того же окружения токен снова не прочитается. max personal doctor покажет, видит ли он токен; как настроить cron — в разделе запуск по расписанию.

«MAX refused this profile's last login for too many attempts»

Код возврата 8. MAX отказал во входе, потому что попыток было слишком много. max запомнил это и до указанного времени сам не входит: ни одна команда, ни max personal session start, ни фоновый сервер. Пауза растёт с каждым отказом подряд: 1 минута, 5 минут, 30 минут, час, 6 часов, дальше сутки. Удачный вход её сбрасывает.

Подождите. Вход раньше срока — ещё одна попытка, которую MAX засчитает, а повторные попытки после такого отказа держат аккаунт заблокированным. Если вход идёт по расписанию, сделайте его реже. max personal doctor покажет, до какого времени пауза.

Как устроены темп запросов, ожидания и параллельные команды — в ограничениях и ожиданиях.

Фоновый сервер (max personal serve, max personal server start) на любом отказе во входе останавливается, а не пробует снова. Сеть, которая пропала, он по-прежнему ждёт и подключается заново.

Команда отвечает, но профиль не тот

Первое слово читается как профиль, если оно не команда. Поэтому опечатка в имени команды превращается в имя профиля:

"chat" is not a command, so it was read as a profile name — and no command followed it.

Команда называется chats, во множественном числе. max --help перечисляет все.

Настройки и значения опций

«is not a valid config»

{"error":{"code":"configuration_error","reason":"config.invalid","message":"…/config.json is not a valid config:\n  profiles.default.limitt: unknown setting — the known ones are limit, timeout_ms, color, record, keep_runs_for_days, read_only, allow, permissions, sends_per_hour, requests_per_minute, embedding_provider, embedding_model, embedding_base_url, embedding_dims, analysis_provider, analysis_model, analysis_base_url, models, sender_colors, catch_up_marks_read, search_catch_up, serve, mcp_tools"}}

Код 3. В файле настроек поле, которого нет в схеме — почти всегда опечатка, и сообщение называет её путь. Отвергается намеренно: молча проигнорированное поле стоит полдня недоумения. Все поля — в справочнике настроек.

«--limit takes a whole number from 1 upwards, not "abc"»

Код 2. То же для --page. Без этой проверки нечисловое значение тихо обрезало бы список до пустого.

«query.invalid-date … use an ISO date, today, yesterday, 30m/2h/7d ago, or a quoted timestamp with offset»

Код 2. Запрос не понял время в date<… или date>…. Он принимает дату ISO 8601, today, yesterday, «сколько назад» или точное время в кавычках, с секундами и смещением:

max personal messages list 0 'date<"2026-09-20T01:00:00Z"'
max personal messages list 0 'date<2h'

Id сообщения — в id<…: время берётся из самого id, читать чат раньше не нужно.

«--at-time takes a time like 2026-09-25T09:00 or a delay like 30m, 2h, 1d»

Код 2. --at-time — местное время или задержка от сейчас в минутах, часах или днях, но не в секундах. Не раньше чем через минуту и не позже чем через год.

«--timeout takes a duration with a unit — 30s, 2m or 500ms»

Код 2. --timeout и MAX_TIMEOUT принимают ms, s или m. Часов нет: два часа — это 120m.

«--all and --page ask for different things; use one or the other»

Код 2. Переданы оба. Отказ, а не выбор одного из них: какой бы ни победил, узнать об этом можно было бы только по неверному ответу.

Поиск чата

«matches N chats»

"Иван" matches 2 chats — name one by its id:
  123  Иван Петров
  456  Иван и друзья

Код 2. Часть названия подошла к нескольким чатам, и программа отказывается угадывать: отправить не в тот разговор нельзя отменить. Назовите точнее или используйте идентификатор из списка.

«no chat matches»

Код 6. Чат с таким именем не найден. Имена берутся из того, что вернул вход: личный чат называется именем собеседника, и если контакт не известен, у чата может не быть названия вовсе — тогда адресуйте его идентификатором из max personal chats list.

Лимиты и права

«profile … has sent N messages in the hour …»

Код 8. Сработал собственный лимит профиля в час — sends_per_hour, по умолчанию 30. В ошибке сказано, когда можно отправить снова. Поднимайте лимит, только если действительно собирались отправить столько: max personal config set sends_per_hour <n>.

«chat … is not on the recipient list of profile …»

Код 7. У профиля включён список получателей, и этого чата в нём нет. Если чат можно, добавьте его сами: max <профиль> recipients add <чат>. Агент здесь должен остановиться и спросить вас (защита от отправки не туда).

«profile … does not let … write» или «profile … denies …»

Код 5, до того как что-то ушло в MAX. Отказали permissions профиля: deny запрещает и чтение, readonly — изменение. В ошибке сказано, какой ключ, где он задан и какая команда его разрешит (права доступа). Агент должен остановиться и спросить вас, а не менять настройку.

«… asks before it acts»

Код 7. Уровень команды — ask, а ответить некому: терминала нет, или команда запущена с --json или --jsonl. Ошибка называет флаг, который отвечает «да»: --allow-dangerous для удаления, --yes для любого другого изменения. Добавляйте его, только если действительно этого хотели. Агент должен остановиться и спросить вас.

Сохранённый лимит

Если мессенджер называет, сколько ждать, max запоминает это время для операции и чата, и повтор до его окончания сразу отказывает с кодом 8, не спрашивая мессенджер. MAX пока такого времени не называет, поэтому для личного аккаунта MAX ничего не запоминается, и отправки не удерживаются. От частых входов max защищает пауза входа: её время показывает max personal doctor.

Запомненные ожидания и удержание отправок видны в max personal server status (поле flood). max flood clear забывает их, ничего не меняя в MAX. Запускайте её, только когда MAX уже не ограничивает аккаунт. В MCP этой команды нет: агент не должен снимать ограничение ради повтора.

MAX и сеть

«MAX answered with something we did not expect»

Строка на stderr, команда при этом работает. Ответ MAX разошёлся с тем, что записано в спецификации: протокол неофициальный и меняется без предупреждения.

Ничего не сломалось — но если после этого в выводе появились пустые поля, дело в этом. Сообщите, приложив строку целиком: в ней есть путь поля и ожидавшийся тип и нет содержимого.

Команда висит

Соединение установлено, ответа нет. Через таймаут будет код 9 и timeout.

max personal chats list --trace

Если видна строка → без парной ← — запрос ушёл и не вернулся: это сеть или MAX, не программа (как читать --trace).

Ограничить можно с двух сторон, и это разные вещи:

max personal chats list --timeout 30s     # на команду целиком, включая вход

Поле timeout_ms в настройках ограничивает один ответ, а команда делает несколько запросов подряд, так что общее время кратно ему. Если нужен предел на всё — это --timeout, и он завершает команду кодом 9, закрыв соединение за собой.

Если строк нет вовсе, а команда всё равно не возвращается — это дефект: сообщите о нём, приложив вывод --trace. Команда, которая напечатала ответ и не вышла, считается здесь поломкой.

После отправки

outcome_unknown после отправки

Код 14. Сообщение могло уйти. Это не ошибка и не успех: ответ не пришёл, а запрос ушёл.

Повторять можно только с тем же --operation-id, который назван в сообщении об ошибке, — MAX схлопнет дубликат:

max personal messages send 0 "текст" --operation-id 1789784741828

Никогда не повторяйте отправку без --operation-id: это второе сообщение человеку.

У max sales bot --operation-id нет: прежде чем повторить, проверьте в чате, ушло ли сообщение.

Ctrl-C

Код 130. Команда остановилась там, где была, и закрыла соединение. Если нажали во время отправки, сообщение могло уйти: посмотрите чат (max personal messages list <чат> --limit 3), прежде чем отправлять снова.

Ответ не «y» на вопрос перед изменением заканчивается так же: ничего не сделано.

Локальная копия и поиск

«the message store was written by a newer version …»

Код 3. Другой CLI — локальная копия общая с tg — или более новый max обновил её так, что эта версия её не прочитает. Запустите max upgrade. Из копии ничего не пропадает.

«two different copies of the store: … — nothing was moved or changed»

Код 3, при первом запуске после обновления. Общая копия один раз переезжает в папку WireCat, а и в старой папке, и в папке WireCat лежит wirecat.db с разным содержимым — обычно потому, что старый max, tg или memo уже после переезда создал новую копию на старом месте. Ничего не изменено. Оставьте нужную копию, другую уберите и запустите команду снова. Обновляйте все CLI с общей копией вместе.

«nothing recorded for profile … yet — run the command once without --offline»

Код 6. --offline отвечает только из локальной копии, а этот профиль ещё ничего в неё не прочитал. Сначала запустите одну команду с подключением, например max personal chats list.

search messages ничего не находит

Поиск по всем чатам читает локальный архив; поиск слов в одном названном чате спрашивает ещё и сервер MAX. Пустой ответ не доказывает, что сообщения нет. Проверьте coverage.next в ответе --json: выполните подсказанную команду или попросите разрешение, затем поищите снова. max personal messages sync --all --background начинает скачивание всех чатов; max personal messages sync <чат> — одного (скачать историю, подготовить архив для поиска).

Пустой список чатов

Сначала проверьте, что смотрите не в локальную копию:

max personal chats list --trace     # видны ли запросы к MAX
max personal contacts sync         # заново получить полный список контактов

Если на первом запуске список был, а на втором подряд пуст — это дефект, сообщите о нём. Контакты на следующем входе могут прийти только изменившиеся; остальное берётся из общей локальной копии.

Фоновый сервер

«max serve is already running for profile …»

Код 2. Один serve на профиль. max personal server status скажет, какой процесс и с какого времени; max personal server stop остановит запущенный через server start или службу.

Сервер в фоне не запускается

Причину покажет max personal server logs. У службы обычная причина — ключница: служба стартует раньше, чем ключница открыта, или без XDG_RUNTIME_DIR. Если перенесли Node или max, снова выполните max personal server install: служба запускает те пути, с которыми её поставили (фоновый сервер).

Как сообщить о проблеме

max personal doctor report          # что попадёт в отчёт и чего в нём не будет
max personal doctor report create   # записать отчёт в файл и показать, как его отправить

create пишет файл max-report-<время>.json в текущий каталог (права 0600). В нём версия, среда и система, то же, что показывает max personal doctor, последний запуск, который кончился ошибкой, и последние 20 действий-записей. Текстов сообщений, названий чатов, имён, номеров телефонов и токена в нём нет. Номера чатов и сообщений заменены метками: внутри одного отчёта метка у чата одна и та же, а в следующем отчёте — другая. Запуск, кончившийся ошибкой, сохраняется сам, даже без --record (неудачный запуск). Про другой запуск — --run <id>, номера показывает max personal runs list.

Дальше команда печатает ссылку на новую задачу в github.com/WireCatLabs/max-cli/issues: заголовок и заготовка текста уже заполнены. Нужен аккаунт на GitHub. Перетащите файл отчёта в поле текста, напишите, что делали и что случилось, и нажмите «Submit new issue».

Задачи на GitHub видны всем, и приложенный файл тоже.

⚠ Не прикладывайте содержимое ~/.cache/max-cli/ и ~/.local/share/WireCat/ — там лежат тексты сообщений.

Частичный результат и действия при ошибке

Каждый неудавшийся элемент частичного результата содержит error с кодом, сообщением и retryable: можно ли повторить этот элемент. retryable не разрешает автоматически повторять запись: при outcome_unknown сначала проверьте, произошло ли действие. Ограничения API нельзя увеличить локальной настройкой; для них уменьшите или разделите входные данные.

HTTP 429 при скачивании вложения прекращает новые файлы в пакете. HTTP 413 означает ограничение провайдера: увеличение локального лимита его не меняет.

У пакетной загрузки или чтения истории отдельный отказ возвращает частичный результат с кодом выхода 0, complete: false и batch или issue. Файлы и предыдущие страницы остаются сохранены. После долгой паузы сервера messages sync одного чата содержит issue.retry_after_ms и границу resume; запрос всех чатов возвращает отдельные issue, а загрузка использует checkpoint. До окончания паузы не повторяйте запросы. Частичное фоновое задание имеет состояние partial и повторяется через max personal store jobs retry. Проверяйте полноту ответа, а не только код выхода.