Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ragnarok22/telegram-bot-api-docker/llms.txt

Use this file to discover all available pages before exploring further.

This guide covers common problems you may encounter when running the Telegram Bot API Docker container and how to resolve them.

​
Common Issues

Error message:
Error: TELEGRAM_API_ID is not set
Error: TELEGRAM_API_HASH is not set
Solution:
  • Ensure TELEGRAM_API_ID and TELEGRAM_API_HASH are present in your .env file
  • Get your credentials from https://my.telegram.org
  • Verify the .env file is correctly loaded with --env-file .env flag
Example .env file:
TELEGRAM_API_ID=12345
TELEGRAM_API_HASH=1234567890abcdef1234567890abcdef
Symptoms:
  • Container fails to write logs
  • Cannot create bot data files
  • Permission denied errors in logs
Solution:
  • Create the ./data directory before first run
  • Ensure the directory is writable by the container user (UID 1000)
  • Check directory permissions:
mkdir -p ./data/logs
chmod -R 755 ./data
Note: The container runs as non-root user botapi:botapi for security.
Symptoms:
  • Container fails to start
  • Error: “Address already in use”
  • Cannot bind to port 8081 or 8082
Solution:
  • Change TELEGRAM_HTTP_PORT and/or TELEGRAM_HTTP_STAT_PORT in your .env file
  • Map matching host ports when running the container
Example with custom ports:
docker run -d --env-file .env \
  -e TELEGRAM_HTTP_PORT=9000 \
  -e TELEGRAM_HTTP_STAT_PORT=9001 \
  -p 9000:9000 -p 9001:9001 \
  ragnarok22/telegram-bot-api-docker
Symptoms:
  • Bot methods return errors
  • Timeout when calling bot endpoints
  • 401 Unauthorized responses
Solution:
  • Check container logs: docker logs <container-name>
  • Review the log file at /data/logs/telegram-bot-api.log
  • Verify your bot token is valid
  • Ensure the container is healthy: docker ps
Test the API:
curl http://localhost:8081/bot<YOUR_TOKEN>/getMe
Diagnosis steps:
  1. Check container status: 
    docker ps -a
  2. View container logs: 
    docker logs <container-name>
  3. Inspect container details: 
    docker inspect <container-name>
Common causes:
  • Missing required environment variables
  • Port conflicts
  • Volume mount permission issues
  • Invalid configuration in TELEGRAM_EXTRA_ARGS
Health check command:
wget -qO- http://localhost:8081/ || exit 1
Check health status:
docker inspect --format='{{json .State.Health}}' <container-name>
Common issues:
  • HTTP port misconfigured (verify TELEGRAM_HTTP_PORT matches exposed port)
  • Container network issues
  • Server failed to start properly
Manual health check:
docker exec <container-name> wget -qO- http://localhost:8081/
Symptoms:
  • Cannot reach Telegram servers
  • Bot updates not received
  • Webhook delivery failures
Solution:
  1. Verify container network: 
    docker network inspect bridge
  2. Test DNS resolution: 
    docker exec <container-name> ping -c 4 api.telegram.org
  3. Check firewall rules and ensure outbound connections are allowed
  4. For custom networks, ensure proper DNS configuration

​
Log Files

The default log file location is /data/logs/telegram-bot-api.log inside the container.

​
Accessing logs

View logs from mounted volume: 
cat ./data/logs/telegram-bot-api.log
View logs from inside container: 
docker exec <container-name> cat /data/logs/telegram-bot-api.log
Custom log location: Set TELEGRAM_LOG_FILE environment variable: 
TELEGRAM_LOG_FILE=/data/custom-bot.log

​
Increase log verbosity

Use TELEGRAM_EXTRA_ARGS to set verbosity level: 
TELEGRAM_EXTRA_ARGS="--log-verbosity-level 3"
Verbosity levels:
  • 0 - Fatal errors only
  • 1 - Errors
  • 2 - Warnings
  • 3 - Info (default)
  • 4 - Debug
  • 5 - Verbose debug

​
Migration Issues

​
Switching from api.telegram.org

To guarantee your bot receives all updates, first deregister it from https://api.telegram.org by calling the logOut method.
Migration steps:
  1. Call logOut on the official API: 
    curl https://api.telegram.org/bot<TOKEN>/logOut
  2. Point your bot client to your local server: 
    http://localhost:8081/bot<TOKEN>/
  3. If using --local mode, ensure your bot handles absolute file paths in getFile responses

​
Moving between local servers

If the same bot is logged in on multiple servers, update delivery is not guaranteed.
Safe migration process:
  1. Call logOut on the old server
  2. Optionally call deleteWebhook, then close to reduce update loss
  3. Move the bot subdirectory (named by bot user ID) from old to new server: 
    cp -r /old-server/data/<BOT_ID> /new-server/data/

​
Getting Help

If you encounter issues not covered here:
  1. Check existing issues: GitHub Issues
  2. Review upstream documentation: Issues with the Telegram Bot API server itself should be reported to tdlib/telegram-bot-api
  3. Join the community: @BotTalk on Telegram
When reporting issues, include:
  • Docker version and platform (amd64/arm64)
  • Container logs
  • Your environment variables (redact sensitive values)
  • Steps to reproduce the issue

Build docs developers (and LLMs) love

Get started for freeTalk to us