Troubleshooting Guide¶

Solutions for common errors and issues.

Table of Contents¶

Telegram Errors
Docker Issues
Health Check Problems
Notification Failures
Performance Issues

Telegram Errors¶

FloodWait Error¶

FloodWait - Telegram Rate Limiting

Symptom: Logs show "FloodWait" error with wait time.

Cause: Telegram rate limiting (too many API requests).

Automatic Handling: Daemon retries automatically after wait time with exponential backoff.

Reduce FloodWait Frequency

If FloodWait errors are persistent:

- TDL_DAEMON_CHECK_INTERVAL=600  # Check every 10 minutes instead of 5

Prevention: Don't check too frequently (minimum 60 seconds recommended).

When to Worry

FloodWait >60 seconds triggers notification. If persistent, you're checking too often or have too many sources.

PEER_ID_INVALID Error¶

PEER_ID_INVALID - Source Access Error

Symptom: "PEER_ID_INVALID" error when accessing source.

Common Causes:

Invalid source URL format
Bot/user doesn't have access to source
Source deleted or banned

Solutions

Verify URL format matches configuration guide
Test access in Telegram app first
For private channels: Ensure you're a member
For forum topics: Verify topic ID is correct

USER_NOT_PARTICIPANT Error¶

USER_NOT_PARTICIPANT - Membership Required

Symptom: "USER_NOT_PARTICIPANT" error.

Cause: You're not a member of the channel/group.

Fix:

Open Telegram app
Join the channel/group
Restart downloader: docker compose restart

CHAT_FORBIDDEN Error¶

CHAT_FORBIDDEN - Access Denied

Symptom: "CHAT_FORBIDDEN" error.

Possible Causes:

You were banned from the source
Source set to private/invite-only
Source was deleted

Resolution:

Check source access in Telegram app
Contact source admin for access
Remove source from configuration if no longer accessible

Authentication Failed¶

Authentication Failed

Symptom: "Authentication failed" or "Invalid phone number".

Step-by-step Fix:

Verify TDL_API_ID and TDL_API_HASH are correct
Check phone number includes country code: +1234567890
Delete session files and re-authenticate:

docker compose down
rm -rf sessions/*
docker compose up -d
docker compose logs -f  # Follow authentication prompts

Docker Issues¶

Container Won't Start¶

Container Exits Immediately

Symptom: docker compose up fails or container exits immediately.

Diagnosis Commands:

# Check logs
docker compose logs

# Check container status
docker compose ps

Common Causes

Missing required env vars (TDL_API_ID, TDL_API_HASH, TDL_PHONE_NUMBER)
Invalid configuration syntax
Port conflicts (rare - this app doesn't expose ports)

Solutions

1. Verify all required environment variables:

docker compose config | grep TDL_API

2. Validate compose file syntax:

docker compose config

3. Check error messages in logs:

docker compose logs --tail=50

Permission Denied Errors¶

Permission Denied - File Write Errors

Symptom: "Permission denied" errors in logs when writing files.

Cause: Volume mount permission mismatch (host UID ≠ container UID).

Fix Permissions

Container runs as UID 1000. Set correct permissions on host:

sudo chown -R 1000:1000 ./downloads ./sessions

Alternative: Use Named Volumes

Instead of bind mounts, use named volumes (Docker manages permissions automatically):

volumes:
  - downloads:/downloads
  - sessions:/app/.sessions

volumes:
  downloads:
  sessions:

Health Check Failing¶

Unhealthy Status

Symptom: docker compose ps shows "unhealthy" status.

Diagnosis Commands:

# Check health file contents
docker compose exec telegram-downloader cat /app/health_status.txt

# Run health check manually
docker compose exec telegram-downloader python3 /app/healthcheck.py
echo $?  # 0 = healthy, 1 = unhealthy

Common Causes

Daemon not enabled (TDL_DAEMON_ENABLED=false)
Daemon crashed (check logs)
Health file stale (daemon stuck)

Solutions

1. Enable daemon mode:

- TDL_DAEMON_ENABLED=true

2. Check logs and restart:

docker compose logs --tail=100
docker compose restart

3. If persistent, increase start period:

healthcheck:
  start_period: 2m  # Give more time to start

Slow Multi-Platform Builds¶

Symptom: Docker builds take >20 minutes.

Cause: QEMU emulation overhead for ARM64.

Solutions: 1. Use build cache (GitHub Actions does this automatically):

docker buildx build --cache-from type=local,src=/tmp/cache ...

2. Build only for your platform locally:

docker build --platform linux/amd64 .

3. Use native ARM64 runners in CI (costs money)

Health Check Problems¶

Status Always "starting"¶

Symptom: Health check shows "starting" status even after start period.

Cause: Daemon not updating health file.

Solution: 1. Check daemon is enabled 2. Verify health file path matches config 3. Check for permission errors in logs

Status "error" But Daemon Running¶

Symptom: Health check shows "error" but logs look normal.

Cause: Last check iteration failed but daemon recovered.

Solution: - This is normal after transient errors (FloodWait, network issues) - Wait for next check cycle (health updates every check interval) - If persistent, check logs for recurring errors

Notification Failures¶

Discord Notifications Not Received¶

Symptom: No Discord messages despite TDL_NOTIFICATIONS_ENABLED=true.

Diagnosis:

# Check logs for notification attempts
docker compose logs | grep notification

Common causes: 1. Invalid webhook URL 2. Webhook deleted in Discord 3. Notifications throttled (too frequent)

Solutions: 1. Test webhook URL manually:

curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"content": "Test message"}'

2. Regenerate webhook in Discord if invalid 3. Check throttle settings: TDL_NOTIFICATIONS_THROTTLE_SECONDS

Too Many Notifications (Spam)¶

Symptom: Flooded with notifications during bulk downloads.

Cause: Notification throttling too aggressive or disabled.

Solution: Increase throttle period:

- TDL_NOTIFICATIONS_THROTTLE_SECONDS=300  # 5 minutes between notifications

Or reduce detail level:

- TDL_NOTIFICATIONS_DETAIL_LEVEL=minimal  # Status only

Performance Issues¶

High Memory Usage¶

Symptom: Container using >512MB RAM.

Diagnosis:

docker stats telegram-downloader

Causes: 1. Large file downloads 2. Many concurrent sources 3. Memory leak (rare)

Solutions: 1. Increase memory limit in docker-compose.yml:

deploy:
  resources:
    limits:
      memory: 1G

2. Reduce concurrent downloads (add to future config) 3. Restart container periodically if memory leak suspected

Slow Downloads¶

Symptom: Downloads slower than expected.

Causes: 1. Network throttling (ISP or Telegram) 2. Large files 3. Distant Telegram data center

Solutions: 1. Check network speed: docker compose exec telegram-downloader curl -o /dev/null https://speed.cloudflare.com/__down?bytes=100000000 2. Verify no FloodWait errors (Telegram rate limiting) 3. Consider VPS in different region if persistent

High CPU Usage¶

Symptom: Container using >50% CPU consistently.

Diagnosis:

docker stats telegram-downloader

Causes: 1. Active download/upload 2. Many sources being checked 3. Inefficient filtering (rare)

Solutions: 1. Reduce check frequency: TDL_DAEMON_CHECK_INTERVAL=600 2. Limit CPU usage in docker-compose.yml:

deploy:
  resources:
    limits:
      cpus: '0.5'

Download Tracking¶

Files Re-Downloaded After Moving¶

Symptom: Files you've already downloaded are being downloaded again after you move or rename them.

Cause: Download tracking may be disabled, or the state database was deleted.

Solutions:

Ensure download tracking is enabled (it's on by default):
```
- TDL_TRACK_DOWNLOADS=true
```
Make sure the sessions volume is persisted — the download history lives in state.db alongside cursor data:
```
volumes:
  - ./sessions:/app/.sessions
```

Want to Re-Download Everything¶

Symptom: You want to force re-download of all files (e.g., after a corrupted download).

Solutions:

Temporarily disable tracking:
```
- TDL_TRACK_DOWNLOADS=false
```
Or delete the state database to reset both cursors and download history:
```
rm ./sessions/state.db
```

Getting Help¶

Still Stuck? Open an Issue

Follow these steps for the best support experience:

1. Gather diagnostic information:

# Docker version
docker --version
docker compose version

# Container logs
docker compose logs > logs.txt

# Configuration (REDACT API CREDENTIALS!)
docker compose config > config.txt

2. Create GitHub issue with:

Title: Brief, descriptive summary
Description: What you tried, what happened, expected behavior
Attachments: Logs and config (redact sensitive info!)

3. Response time: Usually within 24-48 hours

Before Opening an Issue

Most issues are authentication or configuration problems.

Double-check the Configuration Reference first!

Redact Sensitive Information

Always remove before sharing:

API credentials (TDL_API_ID, TDL_API_HASH)
Phone numbers
Webhook URLs
Session files