Troubleshooting Guide
This guide covers common issues, their root causes, and solutions. Organized from most to least common.
Quick Reference Commands
Section titled “Quick Reference Commands”Check Bot Status
Section titled “Check Bot Status”./deploy.sh status # Container status + startup logs./deploy.sh logs -t 100 # Last 100 log lines./deploy.sh follow # Real-time log streamingVerify Environment Variables
Section titled “Verify Environment Variables”./deploy.sh env # Show configured vars (masked)ssh proxmox-main "docker exec signal-bot-selfhosted-signal-bot-1 printenv | grep ADMIN"Database Operations
Section titled “Database Operations”# Connect to databasedocker exec -it signal-bot-postgres psql -U signal_bot signal_bot
# Run a querydocker exec signal-bot-postgres psql -U signal_bot -c "SELECT COUNT(*) FROM signal_messages"Check Bot Health
Section titled “Check Bot Health”ssh proxmox-main "docker exec signal-bot-selfhosted-signal-bot-1 curl -s http://localhost:8080/health | jq"Common Issues
Section titled “Common Issues”Bot Not Responding to Commands
Section titled “Bot Not Responding to Commands”Symptoms: Commands are ignored, no response from bot
Check:
- Bot container running:
./deploy.sh status - Signal-CLI daemon healthy: Check logs for
daemonorRPCerrors - Message timestamps: Check if messages are too old (skip logic)
Solutions:
- Restart container:
./deploy.sh restart - If daemon died silently, full restart:
./deploy.sh deploy - Check watchdog logs for auto-restart notifications
Admin Commands Not Working
Section titled “Admin Commands Not Working”Symptoms: !gtg, !pending, !createuser etc. say “Permission denied”
Root Cause: Admin environment variables not passed to container
Verify:
docker exec signal-bot-selfhosted-signal-bot-1 printenv | grep ADMIN# Should show:# ADMIN_PHONE_NUMBERS=+12345678901# ADMIN_UUIDS=770b19f5-...Solution:
- Check
.envfile hasADMIN_PHONE_NUMBERSandADMIN_UUIDS - Verify
compose.ymlmaps these variables:environment:ADMIN_PHONE_NUMBERS: ${ADMIN_PHONE_NUMBERS}ADMIN_UUIDS: ${ADMIN_UUIDS} - Sync compose.yml and restart:
./deploy.sh deploy
“relation does not exist” Database Errors
Section titled ““relation does not exist” Database Errors”Symptoms: Commands fail with “relation X does not exist”
Root Cause: Database tables not created or missing columns
Solution:
# Apply base schemadocker exec -i signal-bot-postgres psql -U signal_bot signal_bot < database/000_base_schema.sql
# Or apply specific migrationdocker exec -i signal-bot-postgres psql -U signal_bot signal_bot < database/010_breakout_summary_columns.sqlDatabase Connection Issues
Section titled “Database Connection Issues”Symptoms: “Connection refused” or “could not connect to server”
Possible Causes:
- Wrong
DB_HOSTvalue - Postgres container not running
- Network issues between containers
Check:
# Verify postgres is runningdocker compose ps
# Test connectiondocker exec signal-bot-selfhosted-signal-bot-1 psql -h signal-bot-postgres -U signal_bot -c "SELECT 1"Solution:
Use full container name signal-bot-postgres instead of postgres in DB_HOST to avoid DNS conflicts with other databases on shared networks.
Container Shows Old Code After Deployment
Section titled “Container Shows Old Code After Deployment”Symptoms: Code changes not reflected after ./deploy.sh
Root Cause: Docker cache using old layers
Solution:
./deploy.sh deploy --no-cacheMinIO Presigned URL Signature Errors
Section titled “MinIO Presigned URL Signature Errors”Symptoms: SignatureDoesNotMatch when accessing files
Root Cause: Mismatch between internal and public endpoints
Check:
./deploy.sh test-minioExplanation: MinIO requires TWO clients:
- Internal client:
http://minio-irregularchat:9000(for API operations) - Presign client:
https://s3.irregular.chat(for URL generation)
The presigned URL must be generated using the PUBLIC endpoint so signatures match.
Security Issues
Section titled “Security Issues”Command Injection Prevention
Section titled “Command Injection Prevention”The bot has been hardened against command injection:
| Command | Protection |
|---|---|
!calc | Whitelist parser (only 0-9 + - * / ( ) .), no eval() |
!meme | Uses spawn() instead of exec(), no shell interpretation |
If you see suspicious input in logs:
[SECURITY] !calc blocked suspicious input: __import__('os')This is normal - the input was rejected.
Meme Text Overlay Security (Fixed Dec 2025)
Section titled “Meme Text Overlay Security (Fixed Dec 2025)”Previous Vulnerability: !meme 42 $(whoami) executed shell commands
Root Cause: Used exec() which spawns a shell
Solution Applied:
- Changed to
spawn()which passes arguments directly (no shell) - Container now runs as
nodeuser instead of root
Signal-CLI Daemon Issues
Section titled “Signal-CLI Daemon Issues”Bot Goes Silent: Signal Account Not Registered (2026-10-11)
Section titled “Bot Goes Silent: Signal Account Not Registered (2026-10-11)”Symptoms:
- The bot neither receives nor answers.
- The logs say
User +… is not registeredor[403] Authorization failed!. /healthshows"signal_account": { "registered": false … }.- ntfy gets a “relink required” or “re-register” alert.
Root Cause: Signal revoked the account’s registration. Either the linked device was removed or dropped, or the number was registered elsewhere. Restarting cannot fix it, so the bot stops trying.
Fix:
./deploy.sh signal-status # linked or primary? registered?./deploy.sh link # linked device: relink with the phone (QR)./deploy.sh setup primary # primary (or to stop depending on a phone): re-registerWhen re-registering, the captcha must be solved from the bot host’s IP;
setup opens one through the host. A bare 403 from register has several
causes, and setup now handles all of them. Details are in
Bot Setup and the Signal Account and in the
repo’s docs/runbooks/signal-primary.md.
Daemon Silent Death (Fixed Jan 2026)
Section titled “Daemon Silent Death (Fixed Jan 2026)”Symptoms: Bot stops responding, no error logs
Root Cause: Daemon process died, watchdog wasn’t detecting it
Current Protection:
- Multiple detection layers: process state + socket + ping + message flow
- Auto-restart on daemon death
- Notifications to Bot Dev room on restart
Manual Restart:
./deploy.sh restartSkip Old Messages Bug (Fixed Jan 2026)
Section titled “Skip Old Messages Bug (Fixed Jan 2026)”Symptoms: After outage, bot processes all backlogged messages
Root Cause: Only checked one envelope path for timestamps
Current Behavior: The bot checks both:
notification.params.envelope.timestampnotification.params.result.envelope.timestamp
Integration Issues
Section titled “Integration Issues”Authentik SSO Not Working
Section titled “Authentik SSO Not Working”Symptoms: !accountinvite and !createuser fail silently
Check logs for:
Authentik API not configured. Required: AUTHENTIK_BASE_URL and AUTHENTIK_API_TOKENSolution:
Add to .env:
AUTHENTIK_BASE_URL=https://sso.irregularchat.comAUTHENTIK_API_TOKEN=<your-token>AUTHENTIK_INVITE_FLOW_ID=<flow-uuid>Get flow ID:
curl -s -H "Authorization: Bearer <token>" \ "https://sso.irregularchat.com/api/v3/flows/instances/" \ | jq '.results[] | "\(.pk) - \(.slug) - \(.name)"'PeerTube Upload Failures
Section titled “PeerTube Upload Failures”Check:
./deploy.sh test-apiCommon issues:
- Token expired: Get new long-lived token from PeerTube admin
- Network: Verify bot can reach
http://peertube:9000 - Disk space: PeerTube needs space for transcoding
Local AI (Open WebUI) Errors
Section titled “Local AI (Open WebUI) Errors”Symptoms: !lai returns errors
Check:
LOCAL_AI_URLis set correctlyLOCAL_AI_API_KEYis valid- Model exists:
LOCAL_AI_MODEL=irregularbot
Content Extraction Issues
Section titled “Content Extraction Issues”News Article Extraction Failing
Section titled “News Article Extraction Failing”Symptoms: “Couldn’t extract article content for summary”
Current Behavior: Bot uses multi-strategy extraction:
- Googlebot UA + Readability
- Chrome UA + Readability
- archive.today check
- Wayback Machine fallback
Sites that will still fail:
- Heavy JavaScript rendering (SPAs)
- Hard paywalls
- Cloudflare bot protection
- Login-required content
The bot provides bypass/archive links as fallback.
Signal-Generated Long Message Files
Section titled “Signal-Generated Long Message Files”Symptoms: Auto-scan triggers on text messages
Explanation:
Signal converts messages over ~4KB to .txt attachments named like signal-2025-12-18-213038.txt.
Current Behavior: Bot skips these files automatically. They won’t be scanned or archived.
Development Issues
Section titled “Development Issues”Missing Meme Files
Section titled “Missing Meme Files”Symptoms: !meme returns “No memes available”
Check:
docker exec signal-bot-selfhosted-signal-bot-1 ls -la /app/memes/Solution: Ensure memes are synced:
./deploy.sh sync # Syncs memes automaticallyFull Quality Meme Images Not Working
Section titled “Full Quality Meme Images Not Working”Symptoms: !meme add <title> (reply to image) uses thumbnail
Explanation: Signal only provides thumbnails for quoted attachments. The bot now:
- Saves attachment-only messages to database
- Looks up original attachment by timestamp
- Uses full-quality file
Limitation: Only works for images sent AFTER Dec 20, 2025.
Container Crash-Loops After a Dependency Bump: Cannot find module 'undici/lib/...'
Section titled “Container Crash-Loops After a Dependency Bump: Cannot find module 'undici/lib/...'”Symptoms: Fresh --no-cache rebuild deploys, container status shows Restarting (1), logs repeat
Error: Cannot find module 'undici/lib/handler/wrap-handler.js'.
Explanation: jsdom does a deep, non-public require('undici/lib/handler/wrap-handler.js') for
its fetch dispatcher. If anything (an overrides/resolutions pin, or a manual npm install undici@x)
forces undici to a major version whose internal lib/ layout changed, jsdom fails to load at
process start — before any request is even served. This bit a 2026-08-11 undici CVE fix: forcing
undici@8.10.0 fixed the vulnerabilities but broke jsdom@29.1.1’s internal import.
Solution: Don’t force a specific undici major via override unless you’ve confirmed jsdom’s
installed version supports it. Prefer a floor (e.g. "undici": "^7.29.0") over a hard pin, so npm/pnpm
can resolve the newest compatible patch on the already-working major line. Security patches are often
backported to older major versions — check npm view undici versions for a newer patch release before
reaching for a major-version override.
Verify before deploying: npm ls undici should show one resolved version with no overridden
mismatch warnings, and npm audit should be clean. Confirm the crash isn’t present with
docker logs <container> --tail 20 right after ./deploy.sh deploy --no-cache, before trusting the
“Container rebuilt” message alone — a rebuild succeeding says nothing about whether the process stays up.
Server Directory Structure Reference
Section titled “Server Directory Structure Reference”/home/signal-bot-selfhosted/├── .env # Environment variables├── compose.yml # Docker Compose configuration├── Dockerfile.selfhosted # Docker build file├── src/ # Synced bot source code├── signal-data/ # Signal CLI account data (CRITICAL - backup!)├── data/│ ├── postgres/ # PostgreSQL data│ ├── redis/ # Redis data│ ├── backups/ # PostgreSQL backups│ ├── memes/ # Persistent meme storage│ └── pgadmin/ # pgAdmin data (debug profile only)└── database/ # SQL migration scriptsEvent Service Issues
Section titled “Event Service Issues”Event Times Display Wrong (UTC Instead of Eastern)
Section titled “Event Times Display Wrong (UTC Instead of Eastern)”Symptoms: Event shows “2:00 AM Feb 6” instead of “9:00 PM Feb 5”
Cause: Docker container runs in UTC. Date formatting without explicit timezone.
Fixed in v3.21.0: All date formatting now uses timeZone: 'America/New_York'
Event URL Returns 404
Section titled “Event URL Returns 404”Symptoms: Clicking event link shows 404 page
Cause: URL path mismatch - /events/{id} vs /event/{id}
Correct URL format: https://event.irregulars.io/event/{id} (singular)
Fixed in v3.21.0: Bot now uses API-provided URLs
Event Service Not Responding
Section titled “Event Service Not Responding”Check:
curl -s https://event.irregulars.io/health | jqCommon causes:
- Cloudflare Worker deployment needed
- D1 database binding issue
- Missing environment variables in wrangler.toml
Deploy event service:
cd event-service && npx wrangler deployPoll Voting Not Working
Section titled “Poll Voting Not Working”Symptoms: !vote <id> returns “Event not found”
Check:
- Event ID is correct (use
!eventsto see IDs) - Event has active polls (
🗳️indicator) - Partial ID is at least 8 characters
v3.21.0+: Partial event IDs now supported (e.g., !vote d6595bcd)
Q&A System Issues
Section titled “Q&A System Issues”“Could not determine which question to answer”
Section titled ““Could not determine which question to answer””Fixed in v3.21+. This error occurred when !a <hash> <answer> was used with a hash that didn’t match any question in the database. The bot failed to fall back to the most recent question.
If you still see this error:
- Verify the question hash exists:
!questionsor!questions -a - In DMs, you must always specify a valid hash — no fallback to “most recent”
- Check that the question wasn’t deleted or is in a different group
Answer notifications not reaching the right person
Section titled “Answer notifications not reaching the right person”When someone uses !q to quote another person’s message as a question, the original message author should be notified when answers come in — not the person who ran !q.
How it works:
original_author_uuid= the person whose message was quoted (Person A)asker_uuid= also set to Person A (the effective asker)prompter_uuid= the person who ran!q(Person B) — not currently notified
If the original author isn’t getting notifications, check:
SELECT original_author_uuid, asker_uuid, prompter_uuid FROM q_and_a WHERE short_hash = 'ABC123';Cross-group answers not visible in original group
Section titled “Cross-group answers not visible in original group”Added in v3.21+. When someone answers a question from a DM or a different group (using the hash), the bot now posts a notification in the original group where the question was asked. Previously, only a DM notification was sent.
Related Documentation
Section titled “Related Documentation”- Database Schema - Table structure and migrations
- Deployment Guide - Full deployment instructions
- Configuration Reference - All environment variables