# Solución de problemas de la CLI de Telegram (/es/docs/tg/troubleshooting)

Encuentra tu error o síntoma y sigue los pasos de recuperación. El objetivo es volver a usar la herramienta y comprobar el resultado; conserva el texto del error si necesitas ayuda para informar del problema.

Utilice esta página cuando `tg` muestre un error o no haga lo que esperaba. Busque el mensaje que ve, o su código de salida, y la página le indicará lo que significa y qué hacer a continuación. La mayoría de las respuestas requieren una orden.

Algunas palabras que utiliza esta página:

- El **código de salida** es el número que devuelve un comando cuando finaliza: `0` indica que el comando terminó; en lecturas por lotes comprueba la integridad del resultado, cualquier otro número indica el tipo de falla. Los guiones y los agentes de IA lo leen; la siguiente tabla asigna cada uno a su sección.
- **`tg personal doctor`** comprueba la instalación sin conectarse a Telegram. Ejecútelo primero.
- **`--trace`** muestra cada solicitud a Telegram tal como sucede, sin texto de mensaje ([diagnóstico](/llms.mdx/docs/es/tg/diagnostics/content.md)).

En la salida `--json`, un error que termina el comando es una línea en stderr, `{"error":{"code":"…","message":"…"}}`, y el código de salida dice lo mismo que `code`. Cada código también se encuentra en la [referencia del código de salida](/llms.mdx/docs/es/tg/commands/content.md#exit-codes).

## Según el código de salida [#según-el-código-de-salida]

| Código | Nombre | Qué suele significar | Dónde |
|---|---|---|---|
| `1` | `internal_error` | un fallo del propio `tg` | [informar del problema](#report-a-problem) |
| `2` | `validation_error` | una errata en un comando o una opción, un valor o una combinación de opciones que `tg` no acepta; un nombre que coincide con varios chats | [comando desconocido](#unknown-command-), [valores](#--limit-takes-a-whole-number-from-1-upwards), [varios chats](#-matches-3-chats--name-one-by-its-id) |
| `3` | `configuration_error` | `config.json` incorrecto, el proxy rechazó la conexión o no responde, o archivo local más reciente que este `tg` | [configuración](#-is-not-a-setting-of-tg), [proxy](#the-proxy--cannot-be-reached-or--refused), [archivo local](#the-message-store-was-written-by-a-newer-version-) |
| `4` | `authentication_error` | sin sesión, sesión finalizada o llavero inaccesible | [sin sesión](#no-session-for-profile-personal--run-tg-personal-setup-in-a-local-terminal) |
| `5` | `permission_error` | rechazado por `permissions` o por Telegram | [no permitido](#profile--does-not-let--write-or-profile--denies-), [rechazo de Telegram](#telegram-refused-), [PEER_FLOOD](#telegram-limited-this-accounts-messages-as-spam-peer_flood) |
| `6` | `not_found` | chat, mensaje o persona inexistentes; archivo local vacío | [sin chat](#no-chat-matches-), [sin datos guardados](#nothing-recorded-for-profile--yet--run-the-command-once-without---offline) |
| `7` | `confirmation_required` | chat fuera de destinatarios permitidos o cambio que requiere aprobación sin nadie que responda | [destinatarios](#chat--is-not-on-the-recipient-list-of-profile-), [confirmación](#-asks-before-it-acts) |
| `8` | `rate_limited` | límite por hora o espera exigida por Telegram | [límite por hora](#profile--has-sent-n-messages-in-the-hour-), [FLOOD_WAIT](#telegram-asks-to-wait-n-s-before-the-next-request) |
| `9` | `timeout` | Telegram no respondió a tiempo o terminó `--timeout` | [comando bloqueado](#a-command-hangs) |
| `10` | `network_error` | no se puede acceder a Telegram | [conexión](#cannot-reach-telegram-) |
| `11` | `provider_error` | Telegram rechazó la petición | [rechazo de Telegram](#telegram-refused-) |
| `12` | `provider_unavailable` | fallo en Telegram | [fallo de Telegram](#telegram-failed-) |
| `13` | `invalid_response` | respuesta que `tg` no entiende; hasta ahora, solo de my.telegram.org | [my.telegram.org](#mytelegramorg-says-the-app-was-created-but-its-page-shows-none) |
| `14` | `outcome_unknown` | conexión interrumpida después de una escritura; puede haberse realizado | [resultado desconocido](#outcome_unknown-after-a-send) |
| `130` | `cancelled` | Ctrl-C o respuesta negativa a una pregunta | [Ctrl-C](#ctrl-c) |

## Primero: `tg personal doctor` [#primero-tg-personal-doctor]

```sh
tg personal doctor
```

No se conecta y muestra las dependencias de los comandos: versión, entorno, configuración, sesión y credenciales, si `TG_*_DIR` cambió su ubicación, archivo local, registro de envíos y ejecuciones. **Responde incluso cuando todo lo demás falla:** úsalo en ese caso. Un perfil sin sesión aparece como información, no como error; el código sigue siendo `0`. Nunca imprime la sesión ni el hash, solo si existen.

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

`--online` también se conecta una vez y lee la cuenta. No envía nada y no marca nada leído. Sin él, el inicio de sesión se muestra como `not checked`: solo `--online` te dice que Telegram aún acepta la sesión. `--online` también informa un reloj incorrecto en esta computadora y si Telegram congeló o cerró la cuenta ([lo que muestra `tg personal doctor`](/llms.mdx/docs/es/tg/diagnostics/content.md#check-the-installation-tg-personal-doctor)).

## Instalación [#instalación]

### `tg` no se encuentra después de la instalación [#tg-no-se-encuentra-después-de-la-instalación]

La carpeta donde npm instala los comandos no está en `PATH`.

- **Linux y macOS:** es `$(npm prefix -g)/bin`. Añádela a `PATH` en `~/.zshrc` o `~/.bashrc`: `export PATH="$(npm prefix -g)/bin:$PATH"`.
- **Windows:** npm instala comandos en la carpeta indicada por `npm prefix -g`, normalmente `%APPDATA%\npm`. Comprueba que esté en `$env:Path`. Una terminal abierta antes de instalar Node no ve el nuevo `PATH`: abre otra.
- **PowerShell indica "running scripts is disabled on this system".** npm instala `tg.ps1` junto a `tg.cmd` y PowerShell bloquea scripts por defecto. Ejecuta `tg.cmd`, que siempre funciona, o permite scripts para tu usuario: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.
- **Otra `tg` aparece primero.** Otro programa también puede llamarse `tg`. `which -a tg` (o
  `Get-Command tg -All` en PowerShell) los enumera todos; ejecuta el nuestro por su ruta completa o coloca su carpeta
  primero.

También funciona sin instalar: `npx @wirecat/tg-cli personal doctor`.

### `npx @wirecat/tg-cli` ejecuta una versión antigua [#npx-wirecattg-cli-ejecuta-una-versión-antigua]

npx conserva lo descargado. Solicita la última: `npx @wirecat/tg-cli@latest`.

## Inicio de sesión y perfiles [#inicio-de-sesión-y-perfiles]

### "name a profile: `tg <profile> …` — profiles here: …" [#name-a-profile-tg-profile---profiles-here-]

Código de salida `2`. El comando usa una cuenta y nada indica el perfil: ni una primera palabra ni `TG_PROFILE`. `tg` nunca elige uno por su cuenta, aunque solo exista uno. El mensaje enumera los perfiles de este equipo; pon uno delante del comando:

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

En un equipo que todavía no tiene ningún perfil, el mensaje indica que ejecutes `tg personal setup`; cualquier nombre sirve en lugar de `personal`.

### "no session for profile "personal" — run `tg personal setup` in a local terminal" [#no-session-for-profile-personal--run-tg-personal-setup-in-a-local-terminal]

Código de salida `4`. Este perfil nunca inició sesión en esta máquina o cerró sesión. Compruebe a qué perfil se refería: la primera palabra del comando, o `TG_PROFILE` ([perfiles](/llms.mdx/docs/es/tg/sessions/content.md#profiles)).

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

Si sabes que iniciaste sesión, comprueba si `TG_CONFIG_DIR`, `TG_STATE_DIR` o `TG_CACHE_DIR` está ahora definida y antes no, o viceversa, por ejemplo en otra terminal. Cambian dónde se busca la sesión. `tg config show` avisa si hay alguna; `env | grep TG_` las muestra todas.

Si es el primer uso y no hay claves de aplicación, el error indica `tg personal setup` (o `tg work setup` para el perfil work). Lee `tg setup --help` para las opciones de acceso. Los agentes pueden leer `tg skill show` antes de iniciar sesión. Una sesión interrumpida o caducada sigue necesitando `tg personal session start` y después otra comprobación con setup.

### "no Telegram app credentials found … although it has logged in on this machine" [#no-telegram-app-credentials-found--although-it-has-logged-in-on-this-machine]

Código `4`. La sesión existe, pero no se puede acceder al llavero. Ocurre con cron, ssh, servicios y clientes MCP que inician `tg` con un entorno reducido.

**No vuelvas a iniciar sesión:** añadirías otro dispositivo sin arreglarlo. En Linux, define `XDG_RUNTIME_DIR` (normalmente `/run/user/` seguido del número de `id -u`):

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

Para cron, consulte [ejecución programada](/llms.mdx/docs/es/tg/recipes/content.md#running-on-a-schedule). El llavero también puede estar bloqueado hasta que inicie sesión en la computadora. En ese caso, `serve` y una ejecución de `tg personal schedule` terminan con el código `12` (`provider_unavailable`): el servicio vuelve a intentarlo cada 30 s, y una programación diaria o única espera al inicio de sesión y reintenta durante hasta 12 horas.

### "not logged in, or the session was ended — run `tg session start`" [#not-logged-in-or-the-session-was-ended--run-tg-session-start]

Código `4`. Telegram ya no acepta la sesión: se cerró desde otro dispositivo (Ajustes → Dispositivos) o mediante `tg personal session end`. Inicia sesión con `tg personal session start`.

### "`tg session start` asks questions — run it in a terminal" [#tg-session-start-asks-questions--run-it-in-a-terminal]

Código de salida `2`. Un inicio de sesión por teléfono, o un primer inicio de sesión que tiene que registrar la aplicación, necesita que una persona escriba las respuestas. Ejecútelo en una terminal. Un inicio de sesión por QR sin terminal imprime en su lugar el código como texto ([cuando un agente ejecuta el inicio de sesión](/llms.mdx/docs/es/tg/sessions/content.md#when-an-agent-runs-the-login)).

### "the terminal is 40 columns wide and the QR code needs 49" [#the-terminal-is-40-columns-wide-and-the-qr-code-needs-49]

El código no se dibuja, porque un código partido en varias líneas no se puede escanear. Ensancha la terminal: el siguiente código que envíe Telegram se dibujará.

### "my.telegram.org says the app was created, but its page shows none" [#mytelegramorg-says-the-app-was-created-but-its-page-shows-none]

Código de salida `13`, durante `tg personal session start --app auto`. El sitio no tiene API, por lo que `tg` sigue su formulario web y el formulario cambió o respondió inesperadamente. Los otros errores del sitio son el código de salida `11`, con lo que decía el sitio. Utilice la forma predeterminada: `tg personal session start` abre el sitio en su navegador y pega la identificación y el hash de la aplicación ([la aplicación de my.telegram.org](/llms.mdx/docs/es/tg/sessions/content.md#the-app-from-mytelegramorg)).

### La respuesta proviene del perfil equivocado [#la-respuesta-proviene-del-perfil-equivocado]

`tg config show` indica el perfil y su origen. `TG_PROFILE` selecciona uno y `TG_PROFILE_LOCK` rechaza los demás. Una errata en el comando se interpreta como perfil ([abajo](#unknown-command-)).

### "unknown command '…'" [#unknown-command-]

Código de salida `2`. En una terminal es una sola línea con `✗`; con la salida redirigida, es un `validation_error` en JSON por stderr. La primera palabra es el perfil si no es un comando, por lo que una errata en el comando puede convertirse en un nombre de perfil:

```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.
```

Aquí `chat` se interpretó como perfil y `list` no es un comando. El correcto es `chats`, en plural. `tg commands` los muestra todos. Una errata en un comando después del perfil sugiere el correcto: `✗ unknown command 'lst' (Did you mean list?)`. Una opción desconocida da el mismo error, con código de salida `2`.

## Configuraciones y valores de opciones [#configuraciones-y-valores-de-opciones]

### "… is not a setting of tg" [#-is-not-a-setting-of-tg]

Código de salida `3`. `config.json` tiene un ajuste que `tg` no conoce, un valor del tipo incorrecto, o no es
JSON válido. El error nombra el primer problema y, salvo que el JSON esté roto, el `config unset` que lo elimina;
ejecuta ese comando tal como aparece. Se rechaza a propósito: un ajuste ignorado en silencio cuesta medio día.
`tg personal doctor` enumera todos los problemas del archivo ([un error tipográfico es un error](/llms.mdx/docs/es/tg/configuration-reference/content.md#a-typo-is-an-error-not-a-default)).

### "--limit takes a whole number from 1 upwards" [#--limit-takes-a-whole-number-from-1-upwards]

Código `2`. Lo mismo se aplica a `--page`. Sin esa comprobación, un valor no numérico podría vaciar silenciosamente la lista.

### "`id<` takes a message id" [#id-takes-a-message-id]

Código `2`. `id<` e `id>` en una consulta de `messages list` aceptan un identificador de mensaje (`'id<4242'`); `messages comments` dice lo mismo sobre un identificador de comentario. Para una fecha, usa `date>` o `date<`: una fecha ISO 8601 entre comillas (`'date>"2026-09-20T09:00:00+02:00"'`) o un intervalo anterior (`30m`, `2h`, `1d`).

### "--at-time takes a time like 2026-09-25T09:00 or a delay like 30m, 2h, 1d" [#--at-time-takes-a-time-like-2026-09-25t0900-or-a-delay-like-30m-2h-1d]

Código `2`. `--at-time` acepta hora local o un intervalo desde ahora en minutos, horas o días; no segundos. Debe estar entre un minuto y un año en el futuro.

### "--timeout takes a duration with a unit — 500ms, 30s, 2m, 4h or 1d" [#--timeout-takes-a-duration-with-a-unit--500ms-30s-2m-4h-or-1d]

Código `2`. `--timeout` y `TG_TIMEOUT` aceptan un número con `ms`, `s`, `m`, `h` o `d`; un número sin unidad se rechaza.

### "--all and --page ask for different things; use one or the other" [#--all-and---page-ask-for-different-things-use-one-or-the-other]

Código `2`. `--all` pide todas las filas y `--page` una sola página. El programa rechaza la combinación en lugar de elegir silenciosamente y devolver una respuesta incorrecta.

## Encontrar un chat [#encontrar-un-chat]

### "… matches 3 chats — name one by its id" [#-matches-3-chats--name-one-by-its-id]

Código `2`. El título coincide con varios chats. El error los enumera con identificadores y el JSON los incluye como `candidates`. Repite usando el identificador. `tg` nunca adivina: enviar al chat equivocado no se puede deshacer.

### "no chat matches …" [#no-chat-matches-]

Código `6`. Ningún título contiene lo introducido. Prueba `tg personal chats list 'title:*<part of it>*' --offline`, el identificador, `@username` o `me` para Mensajes guardados. El título de un chat individual es el nombre de la otra persona tal como Telegram te lo muestra.

### "Telegram does not know that (…)" [#telegram-does-not-know-that-]

Código `6`. Telegram indica que el chat, usuario, nombre o mensaje no existe para esa cuenta: `PEER_ID_INVALID`, `USERNAME_NOT_OCCUPIED`, `MSG_ID_INVALID`, etc. El mensaje puede haberse eliminado o pertenecer el identificador a otro chat. `contacts lookup` responde "nobody
Telegram lets you find has this number" si la persona oculta su teléfono o no tiene cuenta.

## Límites y permisos [#límites-y-permisos]

### "Telegram asks to wait N s before the next request" [#telegram-asks-to-wait-n-s-before-the-next-request]

Código `8`. Es el límite propio de Telegram (FLOOD_WAIT). Espera ese tiempo; el JSON incluye `retry_after_ms`. Suele aparecer tras muchas peticiones seguidas, como `chats list --all` después de otros comandos o una descarga larga con `messages sync`. Para `messages sync` y `messages download --all`, aumentar `--pause` ayuda.

Un comando espera una petición de hasta 10 segundos, dos veces como máximo, y lo indica en stderr: "Telegram asks to wait 3 s before … — waiting, then going on". `serve` y `watch` esperan hasta 2 minutos. Una espera más larga termina una solicitud independiente con este error; la lectura de historial por lotes devuelve un resultado parcial con `issue` y acciones de recuperación. `tg` también recuerda la espera: hasta que acaba, el mismo comando falla al instante sin volver a preguntar a Telegram, y `tg personal doctor` y `tg personal server status` la muestran en `flood`.

Cómo encajan el ritmo, las esperas y los comandos paralelos: [límites y esperas](/llms.mdx/docs/es/tg/limits/content.md).

### "Telegram limited this account's messages as spam (PEER_FLOOD)" [#telegram-limited-this-accounts-messages-as-spam-peer_flood]

Código `5`. Telegram limita una cuenta que ha escrito a demasiadas personas que no son sus contactos. Puede seguir leyendo. Escribe a @SpamBot desde una aplicación de Telegram: te dice hasta cuándo dura. Volver a enviar lo empeora, así que `tg` retiene todos los envíos durante una hora y lo indica; cada nuevo rechazo reinicia la hora. `tg personal doctor` muestra la retención en `flood.send_block`. Cuando @SpamBot diga que el límite ha terminado, `tg personal flood clear` la levanta, junto con cualquier espera que `tg` recuerde. El rechazo a una cuenta congelada retiene los envíos del mismo modo, hasta la fecha que indica Telegram; `tg personal doctor --online` activa y levanta esa retención.

### "profile … has sent N messages in the hour …" [#profile--has-sent-n-messages-in-the-hour-]

Código `8`. Límite por hora del perfil (`sends_per_hour`, 30 por defecto). El error indica cuándo podrá enviar de nuevo. Auméntalo solo si pretendías enviar esa cantidad: `tg personal config set sends_per_hour <n>`.

### "chat … is not on the recipient list of profile …" [#chat--is-not-on-the-recipient-list-of-profile-]

Código `7`. La lista de destinatarios está activa y el chat no figura en ella. Añádelo tú si quieres autorizarlo: `tg personal recipients add <chat>`. El agente debe detenerse y preguntarte.

### "profile … does not let … write" or "profile … denies …" [#profile--does-not-let--write-or-profile--denies-]

Código de salida `5`, antes de enviar algo a Telegram. El `permissions` del perfil lo rechazó: `deny` también deja de leer, `readonly` detiene un cambio. El error dice qué clave, dónde se configuró y el comando que lo permite ([qué puede hacer un perfil](/llms.mdx/docs/es/tg/configuration-reference/content.md#what-a-profile-may-do)). Un agente debería detenerse y preguntarle, no cambiar la configuración.

### "… asks before it acts" [#-asks-before-it-acts]

Código `7`. El nivel del comando es `ask` y nadie podía responder: falta terminal o se usó `--json` o `--jsonl`. El error indica la opción para aprobar: `--allow-dangerous` para eliminar, `--yes` para otros cambios. Añádela solo si es lo que quieres. El agente debe detenerse y preguntarte.

### Esperas recordadas [#esperas-recordadas]

Cuando Telegram dice cuánto tiempo esperar, `tg` recuerda ese tiempo para la operación y el chat. Un reintento antes de finalizar falla inmediatamente con el código de salida `8`, sin otra solicitud. Un rechazo porque la cuenta está congelada o limitada como spam también puede detener el envío.

`tg personal flood clear` olvida estas esperas y espera en esta computadora. No cambia nada en Telegram, así que ejecútelo solo después de que haya finalizado la restricción. No tiene herramienta MCP: un agente no debe borrar una retención solo para volver a intentarlo. Sólo `tg personal doctor --online` verifica el inicio de sesión, el estado de la cuenta y el reloj; `tg personal doctor` sin él no prueba que el inicio de sesión funcione.

## Telegram y la red [#telegram-y-la-red]

### "Telegram refused: …" [#telegram-refused-]

Telegram rechazó la petición e indicó por qué. Código `5` si la cuenta no tiene permiso; `11` en los demás casos. El nombre después de "refused" es el de Telegram y el JSON lo incluye como `provider_error`; nunca se repite lo introducido. Algunos tienen mensajes específicos:

- **"Telegram transcribes only for Premium accounts…"**: código `5`. Usa un modelo local: `tg personal models download parakeet-v3` y después `tg personal messages transcribe <chat> <id> --local`.
- **"that message is not a voice or video note"**: código `2`; el identificador corresponde a otro tipo de mensaje.
- **"Telegram could not transcribe this voice message"**: código `11`; prueba `--local`.

### "Telegram failed: …" [#telegram-failed-]

Código `12`. Fallo de Telegram. `tg` no cambió nada; reintenta pasado un minuto. Si era un envío, comprueba el chat antes de repetirlo.

### "cannot reach Telegram (…)" [#cannot-reach-telegram-]

Código de salida `10`. No pudo establecerse la conexión o se interrumpió: no hay red, firewall, proxy o DNS. El código entre paréntesis dice cuál (`ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`). Los comandos que responden desde el archivo local funcionan sin red: `tg personal --offline chats list`. Cuando Telegram esté bloqueado, configure un proxy ([configurar un proxy](/llms.mdx/docs/es/tg/configuration-reference/content.md#through-a-proxy)).

### "the proxy … cannot be reached" or "… refused" [#the-proxy--cannot-be-reached-or--refused]

Código `3`. El fallo está en el proxy, no en Telegram: nada llegó a Telegram, así que ni siquiera un envío salió. `tg` se detiene en la primera conexión fallida en lugar de esperar al límite de tiempo.

- **cannot be reached (`ECONNREFUSED`, `ENOTFOUND`, `ETIMEDOUT`)**: el proxy no funciona o su host o puerto son incorrectos.
- **refused: … auth …** o **refused the tunnel (HTTP 407)**: usuario o contraseña incorrectos. Vuelve a configurarlo con `tg personal config set proxy -`.
- **refused the tunnel (HTTP 403 or 502)**: el proxy no quiere o no puede llegar a Telegram.

`tg personal doctor` muestra el proxy en uso, de dónde viene (`TG_PROXY` o la configuración) y si la Bot API pasa por él. Para probar sin él, `tg personal config unset proxy`. Un MTProxy con un secreto incorrecto suele parecer un bloqueo más que un rechazo: limítalo con `--timeout 30s`.

### Un comando se bloquea [#un-comando-se-bloquea]

Todos los comandos puntuales cierran la conexión y terminan. Si Telegram no responde, terminan con código `9` y `timeout`. Para establecer tu propio límite y ver dónde se detiene:

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

`--timeout` cubre todo el comando, incluido el inicio de sesión, y lo finaliza con el código de salida `9` después de cerrar la conexión. En `--trace`, una línea `→` sin `←` después es una solicitud que salió y nunca regresó: la red o Telegram, no `tg` ([leyendo un rastro](/llms.mdx/docs/es/tg/diagnostics/content.md#show-it---trace)).

Si imprime la respuesta pero no termina, es un fallo. Cinco segundos después de terminar la tarea, `tg` identifica lo que sigue abierto (`tg: finished, but … stayed open`) y sale; informa del problema incluyendo esa línea. `watch`, `serve` y `mcp serve` sí están pensados para seguir activos hasta detenerlos.

## Después de un envío [#después-de-un-envío]

### `outcome_unknown` después de un envío [#outcome_unknown-después-de-un-envío]

Código `14`. La conexión se interrumpió después de salir el mensaje, que puede haber llegado. No es éxito ni fracaso. **No lo vuelvas a enviar tal cual.** Repite con el `--operation-id` del error; Telegram elimina la segunda copia:

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

Después de `--at-time`, consulta `tg personal messages scheduled <chat>`: los envíos programados nunca se repiten.

Fijar, desfijar, reaccionar, marcar como leído, borrar, votar, cerrar encuestas y cambiar carpetas o contactos terminan igual cuando Telegram no responde. El mensaje indica si es seguro repetir. Al crear una carpeta no lo es: mira primero en `tg personal chats folders list` o puedes acabar con una segunda carpeta.

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

Código `130`. El comando se detiene y cierra la conexión. Si lo pulsaste durante un envío, el mensaje puede haber llegado: comprueba el chat (`tg personal messages list <chat> --limit 3`) antes de repetirlo. Un `messages sync` en segundo plano continúa; detenlo con `tg personal store jobs cancel <job>`.

Una respuesta distinta de `y` a una confirmación termina igual: no se hizo nada.

## Archivo local y búsqueda [#archivo-local-y-búsqueda]

### "the message store was written by a newer version …" [#the-message-store-was-written-by-a-newer-version-]

Código de salida `3`. Otra CLI, o una `tg` más nueva, actualizó el archivo local de una manera que esta versión no puede leer. Ejecute `tg upgrade`. No se pierde nada en el archivo local ([el archivo local y otras versiones](/llms.mdx/docs/es/tg/archive/content.md#the-store-and-other-versions)).

### "two different copies of the store: … — nothing was moved or changed" [#two-different-copies-of-the-store---nothing-was-moved-or-changed]

Código de salida `3`, en el primer arranque después de una actualización. El almacén local se traslada una sola vez a la carpeta WireCat, y tanto la carpeta antigua como la carpeta WireCat contienen un `wirecat.db` con contenido distinto; normalmente porque una versión anterior de `tg`, `max` o `memo` creó un almacén nuevo en el sitio antiguo después del traslado. No se ha cambiado nada. Conserva el almacén que quieras, aparta el otro y vuelve a ejecutar el comando. Actualiza a la vez todas las CLI que comparten el almacén.

### "nothing recorded for profile … yet — run the command once without --offline" [#nothing-recorded-for-profile--yet--run-the-command-once-without---offline]

Código `6`. `--offline`, `store status` y `store export` solo consultan el archivo local y este perfil todavía no ha guardado nada. Ejecuta primero un comando en línea, como `tg personal chats list`.

### `search messages` no encuentra nada [#search-messages-no-encuentra-nada]

La búsqueda en el archivo (`--backend archive`, `--offline` o `--discover`) lee solo lo que esta máquina ha guardado. Sin esas opciones, la búsqueda normal por palabras también puede consultar Telegram. Un resultado vacío en un historial incompleto no demuestra que nunca se enviara el mensaje. Lee el chat (`tg personal messages list <chat>`) o descarga su historial con `tg personal messages sync` y vuelve a buscar ([búsqueda en el archivo local](/llms.mdx/docs/es/tg/archive/content.md#search)). `tg personal store check` indica qué chats necesitan actualizarse.

### Un chat se lee como recuperado en su totalidad, pero faltan mensajes más antiguos [#un-chat-se-lee-como-recuperado-en-su-totalidad-pero-faltan-mensajes-más-antiguos]

Ejecuta de nuevo `tg personal messages sync <chat>`. Lee por debajo del mensaje más antiguo del archivo local, tanto si el chat se contó como completo como si no, y sigue hasta el primer mensaje del chat; da más margen a `--limit` en un chat largo. Mantén `--page-size` en 100 o menos: Telegram devuelve hasta 100 mensajes por petición.

## Servidor en segundo plano [#servidor-en-segundo-plano]

### "tg serve is already running for profile …" [#tg-serve-is-already-running-for-profile-]

Código `2`. Solo se admite un `serve` por perfil. `tg personal server status` indica proceso y hora de inicio; `tg personal server stop` detiene los iniciados por `server start` o por la unidad.

### `serve` se detuvo solo [#serve-se-detuvo-solo]

`tg personal server logs` indica por qué. Si Telegram cerró la sesión mientras `serve` funcionaba, termina con código `4` en unos 15 minutos y no se reinicia: ejecuta `tg personal session start` y después `tg personal server start`. Si las actualizaciones de Telegram dejaron de llegar por otro motivo, termina con código `12` y systemd lo vuelve a iniciar.

### El servidor en segundo plano no se inicia [#el-servidor-en-segundo-plano-no-se-inicia]

`tg personal server status --json` incluye `stopped` y `unit.exitCode` cuando la última salida normal fue una en la que la unidad no se reinicia. Para la salida 4, renueve la sesión con `tg personal session start`, luego `tg personal server start`. `tg personal server logs` dice por qué. En un servicio, el motivo habitual es el llavero: un servicio se inicia antes de que se abra el llavero, o sin `XDG_RUNTIME_DIR`. Después de mover Node o `tg`, ejecute `tg personal server install` nuevamente: la unidad ejecuta las rutas que lo instalaron ([ejecutándose como servicio](/llms.mdx/docs/es/tg/archive/content.md#as-a-service)).

## Informar de un problema [#informar-de-un-problema]

```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` escribe `tg-report-<time>.json` en la carpeta actual (o `--output`), que solo usted puede leer. Contiene la versión, el tiempo de ejecución y el sistema, lo que responde `tg personal doctor`, la ejecución fallida más reciente (la operación, duración y código de error de cada solicitud) y los últimos 20 intentos de envío, solo el resultado y la duración. Cada ID de chat, mensaje y cuenta se reemplaza por una etiqueta que no significa nada fuera del archivo. No contiene texto de mensaje, títulos de chat, nombres, números de teléfono, credenciales de sesión o aplicación. Una ejecución fallida se mantiene sola, incluso con `record` configurado en `false` ([ejecuciones fallidas](/llms.mdx/docs/es/tg/diagnostics/content.md#a-failed-run-is-always-kept)).

Envíalo como nueva incidencia en [GitHub](https://github.com/WireCatLabs/tg-cli/issues/new): explica qué hiciste y qué ocurrió y adjuntal archivo. Tanto la incidencia como el archivo son públicos: revísalo antes.

⚠ Nunca adjuntes el directorio de estado, la sesión ni `~/.local/share/WireCat/`: contienen tu acceso y tus mensajes.

## Resultados parciales y acciones de recuperación [#resultados-parciales-y-acciones-de-recuperación]

Cada elemento fallido de un resultado parcial contiene `actions`: qué comprobar, qué ajuste cambiar, cuánto esperar o qué elemento omitir.
`retryable` nunca autoriza repetir una escritura automáticamente: ante `outcome_unknown`, comprueba primero si se realizó.
Los límites de API no aumentan con ajustes locales; reduce o divide los datos de entrada.

El fallo de un archivo independiente o una página de historial devuelve un resultado parcial con código de salida `0`,
`complete: false` y `batch` o `issue`. Los archivos y las páginas anteriores permanecen guardados.
Si la pausa del proveedor impide terminar, `messages sync` de un solo chat incluye `issue.retry_after_ms` y un límite `resume`;
la consulta de todos los chats incluye sus respectivos `issue`, y las descargas usan checkpoints. No repitas las solicitudes antes de que termine la pausa.
Un trabajo parcial en segundo plano tiene estado `partial` y se reintenta con `tg personal store jobs retry`. Comprueba la integridad del resultado además del código de salida.
