# Решение проблем с CLI Telegram (/ru/docs/tg/troubleshooting)

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

Используйте эту страницу, когда `tg` показывает ошибку или не делает то, что вы ожидали. Найдите сообщение, которое вы видите, или его код выхода, и страница расскажет вам, что оно означает и что делать дальше. Большинство решений требует одной команды.

Несколько слов, которые используются на этой странице:

- **Код выхода** — это число, которое команда возвращает по завершении: `0` означает завершение команды; у пакетного чтения проверьте полноту, любое другое число обозначает тип сбоя. Его читают скрипты и ИИ-агенты; В таблице ниже каждый из них сопоставлен с его разделом.
- **`tg personal doctor`** проверяет установку без подключения к Telegram. Сначала запустите его.
- **`--trace`** показывает каждый запрос к Telegram в том виде, в каком он происходит, без текста сообщения ([диагностика](/llms.mdx/docs/ru/tg/diagnostics/content.md)).

В выводе `--json` ошибка, завершающая команду, представляет собой одну строку в stderr, `{"error":{"code":"…","message":"…"}}`, и код выхода говорит то же самое, что и `code`. Каждый код также находится в [справке по кодам выхода](/llms.mdx/docs/ru/tg/commands/content.md#exit-codes).

## По коду завершения [#по-коду-завершения]

| Код | Название | Что обычно означает | Где |
|---|---|---|---|
| `1` | `internal_error` | сбой самого `tg` | [сообщить](#report-a-problem) |
| `2` | `validation_error` | опечатка в команде или опции, значение или сочетание параметров, которое `tg` не принимает; имя, совпадающее с несколькими чатами | [неизвестная команда](#unknown-command-), [значения](#--limit-takes-a-whole-number-from-1-upwards), [несколько чатов](#-matches-3-chats--name-one-by-its-id) |
| `3` | `configuration_error` | ошибка `config.json`, прокси отказал или недоступен, либо база новее `tg` | [настройки](#-is-not-a-setting-of-tg), [прокси](#the-proxy--cannot-be-reached-or--refused), [база](#the-message-store-was-written-by-a-newer-version-) |
| `4` | `authentication_error` | нет входа, сессия завершена или хранилище ключей недоступно | [нет сессии](#no-session-for-profile-personal--run-tg-personal-setup-in-a-local-terminal) |
| `5` | `permission_error` | отказ `permissions` профиля или Telegram | [разрешения](#profile--does-not-let--write-or-profile--denies-), [Telegram](#telegram-refused-), [PEER_FLOOD](#telegram-limited-this-accounts-messages-as-spam-peer_flood) |
| `6` | `not_found` | чат, сообщение или человек не найден; база пустая | [чат](#no-chat-matches-), [база](#nothing-recorded-for-profile--yet--run-the-command-once-without---offline) |
| `7` | `confirmation_required` | чат отсутствует в получателях или некому подтвердить действие | [получатели](#chat--is-not-on-the-recipient-list-of-profile-), [подтверждение](#-asks-before-it-acts) |
| `8` | `rate_limited` | часовой лимит или ожидание Telegram | [лимит](#profile--has-sent-n-messages-in-the-hour-), [FLOOD_WAIT](#telegram-asks-to-wait-n-s-before-the-next-request) |
| `9` | `timeout` | Telegram не ответил или сработал `--timeout` | [зависание](#a-command-hangs) |
| `10` | `network_error` | Telegram недоступен | [сеть](#cannot-reach-telegram-) |
| `11` | `provider_error` | Telegram отклонил запрос | [отказ](#telegram-refused-) |
| `12` | `provider_unavailable` | сбой на стороне Telegram | [сбой](#telegram-failed-) |
| `13` | `invalid_response` | `tg` не может прочитать ответ; пока только my.telegram.org | [приложение](#mytelegramorg-says-the-app-was-created-but-its-page-shows-none) |
| `14` | `outcome_unknown` | соединение оборвалось после записи; действие могло выполниться | [неизвестный результат](#outcome_unknown-after-a-send) |
| `130` | `cancelled` | Ctrl-C или отказ от подтверждения | [Ctrl-C](#ctrl-c) |

## Сначала: `tg personal doctor` [#сначала-tg-personal-doctor]

```sh
tg personal doctor
```

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

```sh
tg personal doctor --online
```

`--online` тоже один раз подключается и читает аккаунт. Он ничего не отправляет и ничего не отмечает как прочитанное. Без него логин отображается как `not checked`: только `--online` говорит вам, что Telegram по-прежнему принимает сессию. `--online` также сообщает о неправильных часах на этом компьютере и о том, заморозил ли Telegram или закрыл аккаунт ([что показывает `tg personal doctor`](/llms.mdx/docs/ru/tg/diagnostics/content.md#check-the-installation-tg-personal-doctor)).

## Установка [#установка]

### `tg` не найден после установки [#tg-не-найден-после-установки]

Каталог команд 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` находится первой.** Другая программа тоже может называться `tg`. `which -a tg` (или
  `Get-Command tg -All` в PowerShell) показывает все; вызовите нашу по полному пути или поставьте её папку
  первой.

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

### `npx @wirecat/tg-cli` использует старую версию [#npx-wirecattg-cli-использует-старую-версию]

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

## Вход и профили [#вход-и-профили]

### "укажите профиль: `tg <profile> …` — профили на этом компьютере: …" [#укажите-профиль-tg-profile---профили-на-этом-компьютере-]

Код выхода `2`. Команда работает с аккаунтом, но профиль ничем не указан: нет первого слова, нет `TG_PROFILE`. `tg` никогда не выбирает профиль сам, даже если он всего один. Сообщение перечисляет профили на этом компьютере; поставьте один из них перед командой:

```sh
tg personal chats list         # the profile named in the message
export TG_PROFILE=personal     # or for the whole shell session
```

На компьютере, где ещё нет ни одного профиля, сообщение предлагает выполнить `tg personal setup`; вместо `personal` подойдёт любое имя.

### "нет сессии для профиля "personal" — запустите `tg personal setup` в локальном терминале" [#нет-сессии-для-профиля-personal--запустите-tg-personal-setup-в-локальном-терминале]

Код выхода `4`. Этот профиль ещё не входил в систему на этом компьютере или вышел из системы. Проверьте, какой профиль вы имели в виду: первое слово команды или `TG_PROFILE` ([profiles](/llms.mdx/docs/ru/tg/sessions/content.md#profiles)).

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

### «Учетные данные приложения Telegram не найдены… хотя вход в систему был выполнен на этом компьютере» [#учетные-данные-приложения-telegram-не-найдены-хотя-вход-в-систему-был-выполнен-на-этом-компьютере]

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

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

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

Подробнее о cron см. [работа по расписанию](/llms.mdx/docs/ru/tg/recipes/content.md#running-on-a-schedule). Системное хранилище ключей также может быть заблокировано до тех пор, пока вы не войдёте в систему на компьютере. Тогда `serve` и запуск `tg personal schedule` вместо этого завершаются с кодом `12` (`provider_unavailable`): служба пробует снова каждые 30 с, а ежедневное или разовое расписание ждёт входа и повторяет попытки до 12 часов.

### "не авторизован или сессия завершена — запустите `tg session start`" [#не-авторизован-или-сессия-завершена--запустите-tg-session-start]

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

### "`tg session start` задаёт вопросы — запустите его в терминале" [#tg-session-start-задаёт-вопросы--запустите-его-в-терминале]

Код выхода `2`. Вход по телефону или первый вход, при котором нужно зарегистрировать приложение, требует, чтобы человек ввёл ответы. Запустите его в терминале. Вход по QR без терминала вместо этого печатает код текстом
([когда агент выполняет вход в систему](/llms.mdx/docs/ru/tg/sessions/content.md#when-an-agent-runs-the-login)).

### "ширина терминала 40 столбцов, а QR-коду нужно 49" [#ширина-терминала-40-столбцов-а-qr-коду-нужно-49]

Код не рисуется, потому что перенесённый по строкам код невозможно отсканировать. Расширьте терминал: следующий код, который пришлёт Telegram,
будет нарисован.

### "my.telegram.org сообщает, что приложение было создано, но на его странице ничего не отображается" [#mytelegramorg-сообщает-что-приложение-было-создано-но-на-его-странице-ничего-не-отображается]

Код выхода `13`, во время `tg personal session start --app auto`. На сайте нет API, поэтому `tg` следует за веб-формой, а форма изменилась или неожиданно ответила. Другие ошибки с сайта — это код выхода `11`, как указано на сайте. Вместо этого используйте способ по умолчанию: `tg personal session start` открывает сайт в вашем браузере, и вы вставляете идентификатор и хэш приложения ([приложение из my.telegram.org](/llms.mdx/docs/ru/tg/sessions/content.md#the-app-from-mytelegramorg)).

### Ответ пришел не из того профиля [#ответ-пришел-не-из-того-профиля]

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

### "неизвестная команда '…'" [#неизвестная-команда-]

Код `2`. В терминале это одна строка с `✗`; при выводе в конвейер — `validation_error` в JSON в stderr. Первое слово, не являющееся командой, считается профилем, поэтому опечатка в команде может стать именем профиля:

```text
tg chat list
✗ unknown command 'list' "chat" is not a command, so it was read as a profile name — which left "list" to be one.
```

Здесь `chat` считается профилем, а `list` не является командой. Правильно — `chats`, во множественном числе. Список: `tg commands`. Опечатка в команде после профиля подсказывает правильную:
`✗ unknown command 'lst' (Did you mean list?)`. Неизвестная опция — та же ошибка, код `2`.

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

### «… не является настройкой tg» [#-не-является-настройкой-tg]

Код выхода `3`. В `config.json` есть настройка, которую `tg` не знает, значение неправильного типа, или файл не является
корректным JSON. Ошибка называет первую проблему и, если JSON не сломан, команду `config unset`, которая её
убирает; выполните эту команду как есть. Это намеренный отказ: молчаливо пропущенная настройка стоит полдня.
`tg personal doctor` перечисляет все проблемы в файле ([опечатка — ошибка](/llms.mdx/docs/ru/tg/configuration-reference/content.md#a-typo-is-an-error-not-a-default)).

### "--limit принимает целое число от 1 и выше" [#--limit-принимает-целое-число-от-1-и-выше]

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

### "`id<` принимает идентификатор сообщения" [#id-принимает-идентификатор-сообщения]

Код `2`. `id<` и `id>` в запросе `messages list` принимают идентификатор сообщения (`'id<4242'`); `messages comments` говорит то же про идентификатор комментария. Время указывают в `date>` или `date<`: ISO 8601 в кавычках (`'date>"2026-09-20T09:00:00+02:00"'`) или период назад (`30m`, `2h`, `1d`).

### "--at-time принимает время, например 2026-09-25T09:00, или задержку, например 30 м, 2 часа, 1 д" [#--at-time-принимает-время-например-2026-09-25t0900-или-задержку-например-30-м-2-часа-1-д]

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

### "--timeout принимает время с единицей измерения — 500 мс, 30 с, 2 м, 4 ч или 1 д" [#--timeout-принимает-время-с-единицей-измерения--500-мс-30-с-2м-4ч-или-1д]

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

### "--all и --page запрашивают разные вещи; используйте одно или другое" [#--all-и---page-запрашивают-разные-вещи-используйте-одно-или-другое]

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

## Поиск чата [#поиск-чата]

### "… соответствует 3 чатам — назовите один по его идентификатору" [#-соответствует-3-чатам--назовите-один-по-его-идентификатору]

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

### "нет совпадений в чате..." [#нет-совпадений-в-чате]

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

### «Telegram этого не знает (…)» [#telegram-этого-не-знает-]

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

## Ограничения и разрешения [#ограничения-и-разрешения]

### "Telegram просит подождать N секунд до следующего запроса" [#telegram-просит-подождать-n-секунд-до-следующего-запроса]

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

Команда сама выжидает запрос до 10 секунд, не больше двух раз, и сообщает об этом в stderr: «Telegram asks to wait 3 s before … — waiting, then going on». `serve` и `watch` ждут до 2 минут. Более долгое ожидание завершает отдельный запрос этой ошибкой; пакетное чтение истории возвращает частичный результат с `issue` и действиями для восстановления. `tg` также запоминает ожидание: пока оно не закончится, та же команда сразу завершается ошибкой, не обращаясь к Telegram снова, а `tg personal doctor` и `tg personal server status` показывают его в `flood`.

Как сочетаются темп, ожидания и параллельные команды: [ограничения и ожидания](/llms.mdx/docs/ru/tg/limits/content.md).

### «Telegram ограничил сообщения этого аккаунта как спам (PEER_FLOOD)» [#telegram-ограничил-сообщения-этого-аккаунта-как-спам-peer_flood]

Код `5`. Telegram ограничивает аккаунт, который написал слишком многим людям не из своих контактов. Читать он по-прежнему может. Напишите @SpamBot в приложении Telegram: он скажет, до какого срока. Новые отправки только ухудшают положение, поэтому `tg` задерживает все отправки на час и сообщает об этом; каждый новый отказ начинает час заново. `tg personal doctor` показывает задержку в `flood.send_block`. Когда @SpamBot скажет, что ограничение снято, `tg personal flood clear` снимет задержку вместе с любым ожиданием, которое запомнил `tg`. Отказ замороженного аккаунта задерживает отправки так же — до даты, названной Telegram; `tg personal doctor --online` устанавливает и снимает эту задержку.

### "профиль... отправил N сообщений за час..." [#профиль-отправил-n-сообщений-за-час]

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

### «чат… нет в списке получателей профиля…» [#чат-нет-в-списке-получателей-профиля]

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

### "профиль... не дает... писать" или "профиль... запрещает..." [#профиль-не-дает-писать-или-профиль-запрещает]

Код выхода `5`, прежде чем что-либо будет отправлено в Telegram. `permissions` профиля отказался: `deny` тоже прекращает чтение, `readonly` останавливает изменение. В ошибке указано, какой ключ, где он был установлен, и команда, которая это позволяет ([что может делать профиль](/llms.mdx/docs/ru/tg/configuration-reference/content.md#what-a-profile-may-do)). Агент должен остановиться и спросить вас, а не менять настройку.

### «…спрашивает, прежде чем действовать» [#спрашивает-прежде-чем-действовать]

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

### Запомнил ожидание [#запомнил-ожидание]

Когда Telegram сообщает, сколько времени ждать, `tg` запоминает это время для операции и чата. Повторная попытка до ее завершения сразу же завершается неудачно с кодом выхода `8` без другого запроса. Отказ из-за того, что аккаунт заморожен или ограничен из-за спама, также может приостановить отправку.

`tg personal flood clear` забывает об этих ожиданиях и удержаниях на этом компьютере. В Telegram это ничего не меняет, поэтому запускайте его только после снятия ограничения. У него нет инструмента MCP: агент не должен снимать блокировку только для того, чтобы попытаться еще раз. Только `tg personal doctor --online` проверяет логин, состояние аккаунта и часы; `tg personal doctor` без него не доказывает, что вход работает.

## Telegram и сеть [#telegram-и-сеть]

### «Телеграм отказался:…» [#телеграм-отказался]

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

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

### «Ошибка Telegram: …» [#ошибка-telegram-]

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

### «невозможно связаться с Telegram (…)» [#невозможно-связаться-с-telegram-]

Код выхода `10`. Соединение не удалось установить или оно оборвалось: нет сети, брандмауэра, прокси-сервера или DNS. Код в скобках говорит какой (`ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`). Команды, отвечающие из архива, работают без сети: `tg personal --offline chats list`. Там, где Telegram заблокирован, установите прокси ([настройка прокси](/llms.mdx/docs/ru/tg/configuration-reference/content.md#through-a-proxy)).

### «прокси… недоступен» или «… отказано» [#прокси-недоступен-или--отказано]

Код `3`. Проблема в прокси, а не в Telegram: до Telegram ничего не дошло, поэтому даже отправка не ушла. `tg` останавливается на первом неудачном подключении, а не ждёт истечения срока.

- **недоступен (`ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`)** — прокси не работает или указаны неверные адрес или порт.
- **refused: … auth …** или **refused the tunnel (HTTP 407)** — неверные имя пользователя или пароль. Задайте их снова: `tg personal config set proxy -`.
- **refused the tunnel (HTTP 403 или 502)** — прокси не хочет или не может подключиться к Telegram.

`tg personal doctor` показывает используемый прокси, откуда он взят (`TG_PROXY` или настройки) и идёт ли через него Bot API. Чтобы попробовать без прокси: `tg personal config unset proxy`. MTProxy с неверным секретом обычно выглядит как зависание, а не как отказ: ограничьте время через `--timeout 30s`.

### Команда зависает [#команда-зависает]

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

```sh
tg personal --timeout 30s --trace chats list
```

`--timeout` охватывает всю команду, включая вход в систему, и завершает ее кодом выхода `9` после закрытия соединения. В `--trace` строка `→` без `←` после нее - это запрос, который ушел и больше не вернулся: сеть или Telegram, а не `tg` ([чтение трассировки](/llms.mdx/docs/ru/tg/diagnostics/content.md#show-it---trace)).

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

## После отправки [#после-отправки]

### `outcome_unknown` после отправки [#outcome_unknown-после-отправки]

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

```sh
tg personal messages send <chat> "<the same text>" --operation-id <id from the error>
```

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

Закрепление, открепление, реакция, отметка о прочтении, удаление, голос, закрытие опроса, изменения папок и контактов завершаются так же, когда Telegram не отвечает. Сообщение говорит, безопасно ли повторять. Создание папки повторять небезопасно: сначала посмотрите `tg personal chats folders list`, иначе появится вторая папка.

### Ctrl-C [#ctrl-c]

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

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

## Локальный архив и поиск [#локальный-архив-и-поиск]

### "хранилище сообщений написано более новой версией..." [#хранилище-сообщений-написано-более-новой-версией]

Код выхода `3`. Другой CLI или более новый `tg` обновил локальное хранилище таким образом, что эта версия не может его прочитать. Запустите `tg upgrade`. Ничего в архиве не пропадает ([архив и другие версии](/llms.mdx/docs/ru/tg/archive/content.md#the-store-and-other-versions)).

### "две разные копии хранилища: … — ничего не перемещено и не изменено" [#две-разные-копии-хранилища---ничего-не-перемещено-и-не-изменено]

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

### "для профиля пока ничего не записано — запустите команду один раз без --offline" [#для-профиля-пока-ничего-не-записано--запустите-команду-один-раз-без---offline]

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

### `search messages` ничего не находит [#search-messages-ничего-не-находит]

Поиск в архиве (`--backend archive`, `--offline` или `--discover`) читает только то, что сохранила эта машина. Без этих параметров обычный поиск по словам может также обращаться к Telegram. Пустой результат в неполной истории не доказывает, что сообщение никогда не отправляли. Прочитайте чат (`tg personal messages list <chat>`) или получите его историю с помощью `tg personal messages sync`, затем повторите поиск ([поиск в архиве](/llms.mdx/docs/ru/tg/archive/content.md#search)). `tg personal store check` показывает, какие чаты требуют обновления.

### Чат читается как полученный полностью, но старые сообщения отсутствуют [#чат-читается-как-полученный-полностью-но-старые-сообщения-отсутствуют]

Снова выполните `tg personal messages sync <chat>`. Команда читает сообщения старше самого старого в базе, независимо от того, считался ли чат полным, и доходит до первого сообщения чата; для длинного чата увеличьте `--limit`. Держите `--page-size` не больше 100: Telegram возвращает до 100 сообщений за запрос.

## Фоновый сервер [#фоновый-сервер]

### "tg serve уже запущен для профиля..." [#tg-serve-уже-запущен-для-профиля]

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

### `serve` остановился сам по себе [#serve-остановился-сам-по-себе]

Причина находится в `tg personal server logs`. Если Telegram завершил вход, пока работал `serve`, он примерно в течение 15 минут выходит с кодом `4` и не перезапускается: выполните `tg personal session start`, затем `tg personal server start`. Если обновления Telegram перестали приходить по другой причине, он выходит с кодом `12`, и systemd запускает его снова.

### Фоновый сервер не запускается [#фоновый-сервер-не-запускается]

`tg personal server status --json` включает `stopped` и `unit.exitCode`, когда последний нормальный выход был таким, при котором служба не перезапускается. Для выхода 4 возобновите сессию с помощью `tg personal session start`, затем `tg personal server start`. `tg personal server logs` говорит, почему. В службе обычной причиной является связка ключей: служба запускается до открытия связки ключей или без `XDG_RUNTIME_DIR`. После перемещения Node или `tg` запустите `tg personal server install` еще раз: служба использует пути, с которыми её установили ([запускается как служба](/llms.mdx/docs/ru/tg/archive/content.md#as-a-service)).

## Сообщить о проблеме [#сообщить-о-проблеме]

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

`create` записывает `tg-report-<time>.json` в текущую папку (или `--output`), доступную для чтения только вам. Он содержит версию, среду выполнения и операционную систему, ответ `tg personal doctor`, последний неудачный запуск — операцию каждого запроса, продолжительность и код ошибки — и только последние 20 попыток отправки, результат и длину. Каждый идентификатор чата, сообщения и аккаунта заменяется меткой, которая ничего не значит за пределами файла. Он не содержит текста сообщения, заголовков чатов, имен, номеров телефонов, учетных данных сессии или приложения. Неудачный запуск сохраняется отдельно, даже если `record` установлен в `false` ([неудачные запуски](/llms.mdx/docs/ru/tg/diagnostics/content.md#a-failed-run-is-always-kept)).

Создайте обращение на [GitHub](https://github.com/WireCatLabs/tg-cli/issues/new): опишите действия и результат, приложите файл. Обращение и файл публичные: сначала прочитайте его.

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

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

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

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