Troubleshooting¶

The container stops right after it starts¶

Cause: a setting is missing, and the log names it.

Required environment variable 'PAPERLESS_TOKEN' is not set. The required ones are TELEGRAM_BOT_TOKEN, PAPERLESS_URL and PAPERLESS_TOKEN.
TELEGRAM_ALLOWED_USERS is empty. The bot refuses to start without an allowlist.

Fix: set the variable. For the allowlist, put your Telegram user id in TELEGRAM_ALLOWED_USERS (send /start to @userinfobot to find it). ALLOW_OPEN_ACCESS=true runs the bot open to every Telegram user; it can then upload into, search and download from your archive, so use it only on purpose.

The bot replies "You are not authorized to use this bot"¶

Cause: your Telegram user id is not in TELEGRAM_ALLOWED_USERS.

Fix: add it (comma-separated for several people) and recreate the container.

An upload says "Processing timed out"¶

Cause: Paperless did not report the upload task as finished within UPLOAD_TASK_TIMEOUT seconds (300 by default), for example because its workers are busy. The document often appears in Paperless a little later. (When the bot cannot reach the task API at all, it answers "Processing failed" instead.)

Fix: check Paperless for the document. If processing regularly takes longer than the timeout, raise UPLOAD_TASK_TIMEOUT.

The container is unhealthy¶

Cause: /health on HEALTH_PORT (8080) asks Paperless for one document with your token and answers 503 when that fails. The JSON body says why, for example "paperless": "unreachable: ConnectError".

Fix: check that PAPERLESS_URL is reachable from the container and that PAPERLESS_TOKEN is valid (docker inspect --format '{{json .State.Health}}' paperless-telegram-bot shows the last health check).

Reporting a bug¶

Open an issue with:

the version you run (the version field of /health, or the image tag);
your Paperless-ngx version;
the log around the problem, with LOG_LEVEL=DEBUG if you can reproduce it;
what you sent to the bot and what it answered.

Leave out tokens and document contents.