Решение проблем

Найдите сообщение или симптом и следуйте инструкции. В режиме --json ошибка выводится одной строкой в stderr: {"error":{"code":"…","message":"…"}}. Код завершения соответствует значению code. Числовые коды: Справочник команд.

По коду завершенияCopy Anchor Link

Сначала: tg doctorCopy Anchor Link

tg doctor

Без подключения показывает зависимости команд: версию, среду выполнения, конфигурацию, сессию, данные приложения, переменные TG_*_DIR, базу, журнал отправок и записи запусков. Работает даже при неисправности остальных команд. Отсутствие сессии отображается в результате, а не как ошибка: код остаётся 0. Сессия и хеш не выводятся, только наличие.

tg doctor --online

--online также подключается один раз и читает аккаунт. Ничего не отправляет и не отмечает прочитанным.

После установки команда tg не найденаCopy Anchor Link

Каталог команд npm отсутствует в PATH.

• Linux и macOS. Каталог — $(npm prefix -g)/bin. Добавьте его в PATH через ~/.zshrc или ~/.bashrc: export PATH="$(npm prefix -g)/bin:$PATH".
• Windows. Каталог показывает npm prefix -g, обычно %APPDATA%\npm. Проверьте наличие в $env:Path. Терминал, открытый до установки Node, не видит обновлённый PATH: откройте новый.
• PowerShell сообщает «running scripts is disabled on this system». npm устанавливает tg.ps1 рядом с tg.cmd, а PowerShell по умолчанию запрещает скрипты. Используйте tg.cmd или разрешите скрипты своему пользователю: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
• Раньше находится другой tg. which -a tg или Get-Command tg -All в PowerShell перечислит варианты. Используйте полный путь или поставьте нужный каталог первым.

Без установки доступна команда npx @leemour/tg-cli doctor.

«error: unknown command …» — неизвестная командаCopy Anchor Link

Код 1, справка в stderr вместо JSON. Первое слово, не являющееся командой, считается профилем, поэтому опечатка может стать именем профиля:

tg chat list
error: unknown command 'list'

Здесь chat считается профилем, а list не является командой. Правильно — chats, во множественном числе. Список: tg --help.

"no session for profile "default" — run tg setup"Copy Anchor Link

Код 4. Профиль ещё не входил на этом компьютере или вышел. Проверьте профиль: первое слово команды или TG_PROFILE (Вход и сессии).

tg setup                    # guided first run
tg work chats list          # or name the profile you logged in to

Если вход выполнен, проверьте различия TG_CONFIG_DIR, TG_STATE_DIR, TG_CACHE_DIR между входом и запуском, например в разных терминалах. Они меняют место хранения входа. tg config show показывает заданные переменные; env | grep TG_ — все.

При первом запуске без ключей приложения ошибка предлагает tg setup (или tg work setup для рабочего профиля). Варианты входа описаны в tg setup --help. Агент может прочитать tg skill show до входа. Прерванная или истёкшая сессия требует tg session start, затем повторной проверки настройкой.

Данные приложения не найдены, хотя вход уже выполненCopy Anchor Link

Код 4. Файл сессии есть, но хранилище ключей недоступно. Это бывает в cron, ssh, службах и MCP-клиентах с сокращённым окружением tg.

Не входите повторно: это добавит устройство и не исправит окружение. В Linux задайте XDG_RUNTIME_DIR (обычно /run/user/ и номер из id -u):

XDG_RUNTIME_DIR=/run/user/$(id -u) tg chats list

Для cron: Сценарии использования. Хранилище также может быть заблокировано до входа в систему.

Сессия завершена — выполните tg session startCopy Anchor Link

Код 4. Telegram больше не принимает сессию: её завершили с другого устройства (Настройки → Устройства) или через tg session end. Войдите через tg session start.

tg session start требует терминалаCopy Anchor Link

Код 2. Для входа человек должен отсканировать код или ввести его. Запустите в терминале. Для агента --qr-file login.png сохраняет QR-код файлом (Вход через агента).

my.telegram.org сообщил о создании приложения, но его нетCopy Anchor Link

Код 13 при tg session start --app auto. Сайт не имеет API: веб-форма изменилась или ответила неожиданно. Остальные ошибки сайта дают код 11 с его сообщением. Используйте обычный tg session start: сайт откроется в браузере, затем вставьте идентификатор и хеш (Данные приложения).

Результат относится к другому профилюCopy Anchor Link

tg config show показывает профиль и источник выбора. TG_PROFILE выбирает профиль, TG_PROFILE_LOCK запрещает другие. Опечатка в команде может быть прочитана как профиль (выше).

Ошибка «is not a valid config»Copy Anchor Link

Код 3. В config.json неизвестная tg настройка или неверный тип значения. Ошибка указывает настройку и профиль. Она не игнорируется, чтобы не применять молча неверные значения. Исправьте файл или выполните tg config unset <setting> (Настройки).

Неверное значение --limitCopy Anchor Link

Код 2. --page тоже требует целое положительное число. Иначе неверное значение могло бы молча вернуть пустой список.

Неверное время --after-timeCopy Anchor Link

Код 2. То же для --since-time. Нужен ISO 8601 (2026-09-20T09:00) или период назад (30m, 2h, 1d). Для идентификатора сообщения используйте --after-id или --before-id.

Неверное время --at-timeCopy Anchor Link

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

Неверная длительность --timeoutCopy Anchor Link

Код 2. --timeout и TG_TIMEOUT требуют число с единицей ms, s, m, h, d; число без единицы запрещено.

--all и --page нельзя использовать вместеCopy Anchor Link

Код 2. --all запрашивает все строки, --page — одну страницу. Команда отклоняет сочетание, а не выбирает молча один параметр.

Найдено несколько чатов — укажите идентификаторCopy Anchor Link

Код 2. Название подходит нескольким чатам. Ошибка перечисляет их идентификаторы, JSON — candidates. Повторите с идентификатором. tg не угадывает получателя.

Чат не найденCopy Anchor Link

Код 6. Ни одно название не содержит введённый текст. Попробуйте tg chats list --search <part of it>, идентификатор, @username или me для «Избранного». Личный чат называется именем собеседника в вашем Telegram.

Telegram не знает этот объектCopy Anchor Link

Код 6. Чат, пользователь, имя или сообщение недоступны аккаунту: PEER_ID_INVALID, USERNAME_NOT_OCCUPIED, MSG_ID_INVALID и подобные ошибки. Сообщение могло быть удалено, идентификатор — относиться к другому чату. contacts lookup не находит человека, скрывающего номер или не имеющего аккаунта.

Telegram просит подождать N секундCopy Anchor Link

Код 8. Ограничение Telegram (FLOOD_WAIT). Подождите указанный срок; JSON содержит retryAfterMs. Обычно возникает после серии запросов, например chats list --all или долгого store fetch. Для store fetch и messages download --all увеличьте --pause.

Превышен часовой лимит профиляCopy Anchor Link

Код 8. Лимит профиля — sendsPerHour, по умолчанию 30. Ошибка показывает время следующей отправки. Увеличивайте лимит только намеренно: tg config set sendsPerHour <n>.

Чат отсутствует в разрешённых получателяхCopy Anchor Link

Код 7. Список получателей включён, чат отсутствует. Добавьте его сами при необходимости: tg recipients add <chat>. Агент должен остановиться и спросить вас.

Профиль запрещает действиеCopy Anchor Link

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

Действие требует подтвержденияCopy Anchor Link

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

Telegram отклонил запросCopy Anchor Link

Код 5, если аккаунту запрещено действие, 11 — остальные отказы. Имя причины приходит от Telegram и содержится в JSON как providerError; введённые аргументы не повторяются. Некоторые причины объясняются отдельно:

• Telegram распознаёт речь только для Premium — код 5. Используйте локальную модель: tg models audio download parakeet-v3, затем tg messages transcribe <chat> <id> --local.
• Сообщение не является голосовым или видеозаметкой — код 2: указан другой тип сообщения.
• Telegram не смог распознать речь — код 11; попробуйте --local.

Сбой TelegramCopy Anchor Link

Код 12. Ошибка на стороне Telegram. tg ничего не изменил; повторите через минуту. Если отправляли сообщение, сначала проверьте чат.

Не удаётся подключиться к TelegramCopy Anchor Link

Код 10. Нет сети, мешает firewall, прокси или DNS, либо соединение оборвалось. Код в скобках уточняет причину: ECONNREFUSED, ENOTFOUND, ETIMEDOUT. Локальные команды работают без сети: tg --offline chats list.

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

Код 14. Соединение оборвалось после отправки, и сообщение могло уйти. Не отправляйте его повторно без изменений. Используйте --send-id из ошибки: Telegram исключит дубликат.

tg messages send <chat> "<the same text>" --send-id <id from the error>

После --at-time проверьте tg messages scheduled <chat>: отложенная отправка никогда не повторяется.

Команда завислаCopy Anchor Link

Одноразовые команды закрывают соединение и выходят. Без ответа Telegram команда завершается с кодом 9 и timeout. Чтобы ограничить время и увидеть место остановки:

tg --timeout 30s --trace chats list

--timeout охватывает всю команду, включая вход, закрывает соединение и завершает с кодом 9. В --trace строка → без ← означает запрос без ответа: проблема сети или Telegram (Диагностика).

Если результат выведен, но команда не выходит, это сбой. Через пять секунд tg перечисляет открытые ресурсы (tg: finished, but … stayed open) и выходит. Приложите эту строку к обращению. watch, serve, mcp должны работать до остановки.

Ctrl-CCopy Anchor Link

Код 130. Команда остановлена и соединение закрыто. При остановке отправки сначала проверьте чат (tg messages list <chat> --limit 3): сообщение могло уйти. Фоновый store fetch продолжит работу; остановите через tg store jobs cancel <job>.

Ответ кроме y на запрос подтверждения даёт тот же код; действие не выполнено.

База записана более новой версиейCopy Anchor Link

Код 3. Другой CLI или новый tg обновил базу до несовместимой структуры. Выполните tg upgrade. Данные не теряются (Локальная база).

Для профиля пока нет сохранённых данныхCopy Anchor Link

Код 6. --offline, messages search, store status, store export читают только локальную базу, а профиль ещё ничего не сохранил. Сначала выполните онлайн-команду, например tg chats list.

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

Поиск не запрашивает Telegram. Пустой результат означает отсутствие сохранённых данных, а не самого сообщения. Прочитайте чат (tg messages list <chat>) или загрузите историю через tg store fetch, затем повторите (Поиск). tg store check показывает отстающие чаты.

tg serve уже работает для профиляCopy Anchor Link

Код 2. Разрешён один serve на профиль. tg server status показывает процесс и время запуска; tg server stop останавливает запущенный через server start или службу.

Фоновый сервер не запускаетсяCopy Anchor Link

Причина находится в tg server logs. Обычно служба не видит хранилище ключей: оно ещё закрыто или нет XDG_RUNTIME_DIR. После переноса Node или tg повторите tg server install: служба использует пути времени установки (Служба).

npx @leemour/tg-cli запускает старую версиюCopy Anchor Link

npx сохраняет скачанное. Запросите новую версию: npx @leemour/tg-cli@latest.

Сообщить о проблемеCopy Anchor Link

tg doctor report           # what a report holds, and what it never holds; writes nothing
tg doctor report create    # write it to a file, and say where to send it
tg doctor report create --run <id>    # about another run; ids from tg runs list

create записывает tg-report-<time>.json в текущий каталог или --output, доступный только вам. Внутри версии программы, среды и системы, результат tg doctor, последний неудачный запуск (операции, длительности, ошибки) и 20 последних попыток отправки без текста, только результат и длина. Идентификаторы чатов, сообщений и аккаунтов заменены метками, значимыми лишь внутри файла. Текстов, названий, имён, телефонов, сессий и данных приложения нет. Ошибки сохраняются автоматически без --record (Отчёт).

Создайте обращение на GitHub: опишите действия и результат, приложите файл. Обращение и файл публичные: сначала прочитайте его.

⚠ Не прикладывайте каталог состояния, файл сессии или ~/.local/share/cli-messaging/: они содержат доступ к аккаунту и ваши сообщения.