> ## Documentation index
> Fetch the complete documentation index at: https://tgcloud.docs7.io/llms.txt
> Ask it with GET https://tgcloud.docs7.io/ask?q=<keywords or question>. Short keywords rank best.
> Use these to discover all available pages before exploring further.

# Troubleshooting

> Common errors and fixes

# Troubleshooting

## `"tgcloud login" requires an interactive terminal`

The CLI needs a TTY. Use the `login_bot` tool — it pipes the token via stdin
with `TGCLOUD_ASSUME_TTY=1`. For CI: `TGCLOUD_TOKEN='app...'`.

## `Token format looks wrong. Expected "app<id>:<secret>"`

You passed the Bot API token. Get the **CLI access token**:
@BotFather → bot → Serverless → CLI Access.

## `Could not reach the tgcloud server`

`cloud.telegram.org` is unreachable. Check network and proxy; route the CLI via a
wrapper (`HTTPS_PROXY` + `NODE_USE_ENV_PROXY=1`) through `TGCLOUD_CLI`.

## `This bot already has N deployed modules (revision R)`

Cloud and project are out of sync: `fetch` → `diff` → `push`
(or, knowingly, `push { force: true, confirm: true }`).

## `non-interactive session — specify --safe, --yes, or --dry-run`

Use `migrate`. The default is `--dry-run`. Applying needs `dry_run: false` and
`confirm: true`. `apply: "safe"` maps to `--safe` (skip warning drops).
`apply: "yes"` maps to `--yes` (apply warning drops, skip manual type changes).

## Commands refuse a project that has `schema.js` at the root

That is a pre-0.2.0 layout. `upgrade` with `dry_run: true`, then
`upgrade { dry_run: false, confirm: true }`.

## `chat not found` in `run_handler`

Expected with a fake chat id: database writes succeed, only the real Telegram
delivery fails. Handler logic still runs.

## No logs from a deployed bot

There is no command that downloads a deployed bot's logs. `tgcloud run`
(`run_handler`) captures `console.*`, but it runs your local files on the
platform without deploying — it is not the deployed bot's output. To diagnose a
deployed failure, read `webhook_status` (`tgcloud webhook`): the last delivery
error and the sync state are the first clues. Then reproduce the path with
`run_handler`.

## Mini App shows an old front-end

`push` does not run the bundler. Call `deploy`, or build and then push.
`immutable` in `tgcloud.jsonc` caches matched files for a year — use it only
for content-hashed paths such as `/assets/*`.