TgWitness / Documentation

Repository / docs/wiki/Troubleshooting.md

Troubleshooting

Find the cause. Check the symptom, follow the record and confirm recovery.

05 · FIND AN ANSWER · All guides · Get help

On this page

Before you touch settings, write down how it's installed, the version, which workspace and the exact step. Test fixes in a chat you control.

Find the failing step#

Symptom Look at Then
Panel won't open Process output, port, container status Run the readiness check, make sure nothing else holds the port
Token rejected Live vs demo, native vs Docker, whole token copied Take the token from the install you're actually using
Connection test fails Proxy host, port, type, secret Fix the route and test before signing in
QR expires Right workspace, latest QR Get a new code and approve it in the right account
Imported JSON won't log in Does it have a session or just metadata Use the session file or phone/QR
Connected but nothing new Account ID, access, scope, exclusions, events, observation on Send a fresh message after starting
Deleted message has no text Was it saved before deletion Then the text is unknown, nothing can restore it
Attachment queued or missing Collector running, type/size policy, disk, failure record Fix it and check the receipt, queued isn't saved
Browser can't save the export Streaming support, size Use the download CLI, then verify
Verification fails Right fingerprint, complete file, password wrapper Keep the originals, never "fix" the journal
Witness polls but doesn't post Post policy, bot/channel rights, witness log Check the channel itself
Deletion incomplete Programs holding its files Close them, retry Delete

Check local prerequisites#

From a source installation:

python start.py --check --json

No environment yet? python start.py --setup-only. A busy port might be your own running collector, use another --port for the check instead of killing things.

For Docker:

docker compose ps
docker compose logs --tail 100 tgwitness

Add the same -f options used when starting an overlay deployment.

Telegram asks for a pause#

Wait out the FloodWait. Cut down on snapshots and repeated actions. Logging in again and again or running copies of the same session only makes it worse.

Uncertain action result#

Unknown result for a send, join or bot press? Look at the chat and the receipt before retrying. A timeout doesn't mean Telegram said no.

Still stuck?#

See Get help. Send redacted errors and a repro with fake data. Never attach a data directory, session, token, key or real evidence. Vulnerabilities go through the security process.

Related: Account troubleshooting · Operations · FAQ