Telegram 5-20MB File Deadlock
Open Upstream Issue — Workaround Only
This behavior is tracked in openclaw/openclaw#27984. When a Telegram user uploads a file in the 5-20MB range, the bot goes completely silent — no reply, no error, no timeout. The only recovery is a gateway restart.
This is one of the most frustrating OpenClaw bugs because there's zero visible feedback. The bot just stops responding in the affected Telegram channel. Other channels (Discord, Slack, web) continue to work fine. The deadlock only affects the specific Telegram chat where the file was uploaded.
Next Step
Fix now, then reduce repeat incidents
If this issue keeps coming back, validate your setup in Doctor first, then harden your config.
Jump to Section
How to Identify the Deadlock
The deadlock has a very specific signature that distinguishes it from other Telegram issues:
Bot goes silent after a file upload
No reply, no error message, no typing indicator. The bot appears to be ignoring all messages.
Only one Telegram chat is affected
Other Telegram chats, Discord, Slack, and web interface continue to work normally.
The uploaded file was 5-20MB
Check the file size in the Telegram chat. Files <5MB or >20MB do not trigger this bug.
Gateway logs show no errors
The logs don't show a crash or exception — the processing pipeline is silently stuck.
Text messages sent after the file are also ignored
The deadlock blocks the entire channel queue, not just the file message.
# Look for the last successful message vs current time gap openclaw logs --tail 300 | grep -Ei "telegram" # You should see: # - Normal message processing up to the file upload # - Then silence — no more telegram lines after the file event # - No error, no timeout, no retry
Why This Happens
Telegram Bot API file download buffer
When OpenClaw receives a file from Telegram, it downloads the file content via the Bot API before processing. For files in the 5-20MB range, the download starts successfully and fills an internal buffer. The issue is that the completion callback — the function that signals "download finished, continue processing" — is never called for certain file sizes and content types.
No timeout on the download operation
The Telegram file download path does not have a timeout. When the completion callback is never fired, the processing pipeline waits indefinitely. There's no watchdog timer to detect "this download has been pending for too long" and abort it.
Channel queue is blocked, not the gateway
The deadlock occurs at the channel level, not the gateway level. Each Telegram chat has its own processing queue. When one queue is stuck waiting for a file download to complete, all subsequent messages in that specific chat queue up behind it. Other channels (even other Telegram chats) are unaffected because they have separate queues.
Fix: Unblock Now (60 Seconds)
openclaw gateway restart
openclaw gateway status
After restart, send a text-only message (no files, no images) in the affected Telegram chat to confirm the channel is processing again.
The restart clears all in-flight channel queues. The stuck file download is abandoned and the channel resumes normal operation. Messages sent during the deadlock are lost — they won't be retroactively processed.
Prevent Recurrence
Avoid direct file uploads in the 5-20MB range
OperationalUntil the upstream fix ships, instruct users to share files as links (Google Drive, Dropbox, S3 presigned URL) rather than direct Telegram uploads. Files under 5MB are safe.
Add a file size filter to your agent prompt
LowInclude in your agent's system prompt: "If a user uploads a file larger than 5MB, ask them to share it as a download link instead." This prevents the deadlock from being triggered.
Set a gateway-level file size limit
LowConfigure the maximum file download size in your OpenClaw config to reject files that would trigger the deadlock.
openclaw config set channels.telegram.maxFileSize 5000000 openclaw gateway restart # Files > 5MB will be rejected with a user-friendly message # instead of silently deadlocking
Set Up Monitoring
Since the deadlock produces no error, you need proactive monitoring to detect it. The signal is silence — no Telegram activity for an unusual period.
#!/bin/bash
# Save as ~/check-telegram-deadlock.sh
# Run via cron every 5 minutes: */5 * * * * ~/check-telegram-deadlock.sh
LAST_MSG=$(openclaw logs --tail 500 | grep -i telegram | tail -1)
LAST_TIME=$(echo "$LAST_MSG" | grep -oP '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}')
if [ -z "$LAST_TIME" ]; then
echo "No recent Telegram activity — possible deadlock"
# Add your alerting here (webhook, email, etc.)
# Optionally auto-restart:
# openclaw gateway restart
fiBe careful with auto-restart — it will interrupt any in-progress agent tasks across all channels, not just the deadlocked one. In production, send an alert first and let a human decide whether to restart.
Verify Recovery
# 1. Gateway should be healthy openclaw gateway status # 2. Send a text message in the affected Telegram chat # and verify the bot responds # 3. Check logs show new Telegram activity openclaw logs --tail 50 | grep -i telegram # 4. Run doctor for overall health openclaw doctor
Recovery is confirmed when the bot responds to a text message in the previously-deadlocked chat AND you see new telegram lines in the gateway logs. If the bot responds but logs don't update, check if you're reading logs from the correct gateway instance.
Track issue #27984 for the upstream fix. When it ships, remove the file size limit and monitoring script, and update your agent prompt to re-allow file uploads.
Still Stuck?
If the bot remains silent after gateway restart, the issue may be different:
Bot token was revoked by Telegram
Check your bot in @BotFather. Regenerate the token if needed and update your config.
Telegram webhook URL changed
If you use webhooks (not polling), verify your webhook URL is still valid and pointing to the right gateway.
Channel was removed from config
Check openclaw config get channels.telegram to verify the chat is still listed.
Run the Doctor
Checks channel configuration, bot token validity, gateway health, and Telegram API connectivity.
Related Issues
Similar channel and delivery problems:
Fix It Faster With Our Tools
Config Wizard
Generate a production-ready clawhub.json in 30 seconds.
Local Doctor
Diagnose Node.js, permissions, and config issues instantly.
Cost Simulator
Calculate your agent burn rate before you get surprised.
Gateway Monitor
Detect token spikes and gateway incidents before users complain.
Skill Finder
Describe your use case and find the right Claude Code skill instantly.
Did this guide solve your problem?