Solución de problemas

Busca el síntoma que ves en pantalla y sigue los pasos. Con --json, cada error es una línea por stderr, {"error":{"code":"…","message":"…"}}, y el código de salida corresponde a code. Consulta los números en códigos de salida.

Según el código de salidaCopy Anchor Link

Primero: tg doctorCopy Anchor Link

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

tg doctor --online

--online también se conecta una vez y lee la cuenta. No envía nada ni marca mensajes como leídos.

No se encuentra tg después de instalarCopy Anchor Link

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.
• Hay otro tg antes en la ruta. which -a tg (o Get-Command tg -All en PowerShell) muestra todos. Ejecuta el nuestro mediante su ruta completa o coloca su carpeta primero.

También funciona sin instalar: npx @leemour/tg-cli doctor.

"error: unknown command '…'"Copy Anchor Link

Código de salida 1; muestra ayuda por stderr, no JSON. La primera palabra es el perfil si no es un comando, por lo que una errata en el comando se interpreta como perfil:

tg chat list
error: unknown command 'list'

Aquí chat se interpretó como perfil y list no es un comando. El correcto es chats, en plural. tg --help muestra todos.

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

Código 4. El perfil nunca inició sesión en este equipo o la cerró. Comprueba qué perfil querías usar: primera palabra o TG_PROFILE (perfiles).

tg 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 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 session start y después otra comprobación con setup.

"no Telegram app credentials found … although it has logged in on this machine"Copy Anchor Link

Código 4. La sesión existe, pero no se puede acceder al almacén de claves. 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):

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

Para cron, consulta tareas programadas. El almacén también puede permanecer bloqueado hasta que inicies sesión en el equipo.

"not logged in, or the session was ended — run tg session start"Copy Anchor Link

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

"tg session start asks questions — run it in a terminal"Copy Anchor Link

Código 2. El inicio necesita una persona que escanee o introduzca un código. Ejecútalo en una terminal. Para un agente, --qr-file login.png guarda el QR en un archivo (sesiones).

"my.telegram.org says the app was created, but its page shows none"Copy Anchor Link

Código 13 durante tg session start --app auto. El sitio no tiene API y tg usa el formulario web; este cambió o respondió inesperadamente. Los demás errores del sitio tienen código 11 e incluyen su mensaje. Usa la vía predeterminada: tg session start abre el navegador para que pegues el identificador y hash (sesiones).

La respuesta procede de otro perfilCopy Anchor Link

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 (arriba).

"… is not a valid config"Copy Anchor Link

Código 3. config.json contiene un ajuste desconocido para tg o un valor de tipo incorrecto. El error identifica ajuste y perfil. Se rechaza intencionadamente: ignorarlo ocultaría el problema. Corrígelo manualmente o quítalo con tg config unset <setting> (configuración).

"--limit takes a whole number from 1 upwards"Copy Anchor Link

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

"--after-time takes an ISO 8601 time or 30m, 2h, 1d ago"Copy Anchor Link

Código 2. --since-time exige el mismo formato. Aceptan fechas ISO 8601 (2026-09-20T09:00) o intervalos anteriores (30m, 2h, 1d). Para identificadores de mensaje, usa --after-id o --before-id.

"--at-time takes a time like 2026-09-25T09:00 or a delay like 30m, 2h, 1d"Copy Anchor Link

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"Copy Anchor Link

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"Copy Anchor Link

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.

"… matches 3 chats — name one by its id"Copy Anchor Link

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 …"Copy Anchor Link

Código 6. Ningún título contiene lo introducido. Prueba tg chats list --search <part of it>, 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 (…)"Copy Anchor Link

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.

"Telegram asks to wait N s before the next request"Copy Anchor Link

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

"profile … has sent N messages in the hour …"Copy Anchor Link

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

"chat … is not on the recipient list of profile …"Copy Anchor Link

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

"profile … does not let … write" or "profile … denies …"Copy Anchor Link

Código 5, antes de enviar nada a Telegram. Los permissions del perfil lo rechazan: deny bloquea también lectura; readonly bloquea cambios. El error indica clave, origen y comando para permitirlo (configuración). El agente debe detenerse y preguntarte, sin modificar el ajuste.

"… asks before it acts"Copy Anchor Link

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.

"Telegram refused: …"Copy Anchor Link

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 providerError; nunca se repite lo introducido. Algunos tienen mensajes específicos:

• "Telegram transcribes only for Premium accounts…": código 5. Usa un modelo local: tg models audio download parakeet-v3 y después tg 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: …"Copy Anchor Link

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 (…)"Copy Anchor Link

Código 10. No se pudo conectar o se interrumpió: red, cortafuegos, proxy o DNS. El código entre paréntesis identifica la causa (ECONNREFUSED, ENOTFOUND, ETIMEDOUT). Los comandos del archivo local funcionan sin red: tg --offline chats list.

outcome_unknown después de enviarCopy Anchor Link

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 --send-id del error; Telegram elimina la segunda copia:

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

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

Un comando se queda bloqueadoCopy Anchor Link

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:

tg --timeout 30s --trace chats list

--timeout cubre todo el comando, incluido el inicio de sesión, y termina con código 9 después de cerrar la conexión. En --trace, una línea → sin ← posterior es una petición sin respuesta: problema de red o Telegram, no de tg (diagnóstico).

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 sí están pensados para seguir activos hasta detenerlos.

Ctrl-CCopy Anchor Link

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 messages list <chat> --limit 3) antes de repetirlo. Un store fetch en segundo plano continúa; detenlo con tg store jobs cancel <job>.

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

"the message store was written by a newer version …"Copy Anchor Link

Código 3. Otro CLI o un tg más reciente actualizó el archivo de forma incompatible con esta versión. Ejecuta tg upgrade. No se pierde nada (archivo local).

"nothing recorded for profile … yet — run the command once without --offline"Copy Anchor Link

Código 6. --offline, messages search, 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 chats list.

messages search no encuentra nadaCopy Anchor Link

Solo busca lo guardado en este equipo, nunca en Telegram. Vacío significa «no guardado», no «nunca se dijo». Lee el chat (tg messages list <chat>) o descarga el historial con tg store fetch y busca de nuevo (archivo local). tg store check identifica chats desactualizados.

"tg serve is already running for profile …"Copy Anchor Link

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

El servidor en segundo plano no se iniciaCopy Anchor Link

tg server logs indica por qué. En un servicio, suele deberse al almacén de claves: se inicia antes de que se desbloquee o sin XDG_RUNTIME_DIR. Si cambias la ubicación de Node o tg, ejecuta tg server install de nuevo: la unidad utiliza las rutas de instalación (archivo local).

npx @leemour/tg-cli ejecuta una versión anteriorCopy Anchor Link

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

Informar de un problemaCopy 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 escribe tg-report-<time>.json en la carpeta actual (o --output), legible solo por ti. Contiene versión, entorno, sistema, respuesta de tg doctor, última ejecución fallida —operación, duración y código de error de cada petición— y los últimos 20 intentos de envío, solo resultado y longitud. Cada identificador de chat, mensaje o cuenta se sustituye por una etiqueta que no tiene significado fuera del archivo. No contiene texto, títulos, nombres, teléfonos, sesión ni credenciales. Los fallos se guardan automáticamente aunque no uses --record (diagnóstico).

Envíalo como nueva incidencia en GitHub: explica qué hiciste y qué ocurrió y adjunta el 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/cli-messaging/: contienen tu acceso y tus mensajes.