Troubleshooting

Published from docs/troubleshooting.md. To change this page, edit the source guide and open a pull request.

Troubleshooting

Start with the status and console output on the Main tab. Compare progress with your Twitch inventory, since a dashboard display and Twitch's recorded progress can differ.

The login browser does not open or connect

• Use the current published Docker image or source build with the integrated browser. Check container resources and use the supplied init process, 30-second stop grace period and shared memory size.
• Set TZ to the timezone of your home internet connection. A mismatch can produce Twitch’s “browser not supported” message. Check the host clock as well.
• Complete login and any email/2FA verification before selecting Finish sign in. Selecting it too early produces LOGIN_MISSING; use Retry for a fresh attempt.
• A closed viewer can be reconnected with Retry. Reverse proxies must forward WebSocket upgrades for /api/session/vnc. Unlock a password-protected dashboard first.
• BROWSER_UNAVAILABLE means required Linux browser/display tools are missing. Use Docker or install the dependencies in the login guide.
• BROWSER_ISOLATION means the browser user cannot be separated from the miner or the data/log mount ignores private permissions. Use the unmodified Docker image with a Linux filesystem or Docker named volumes.
• BROWSER_START, BROWSER_FAILED or BROWSER_STOP indicates a browser/display or cleanup failure. Check memory, process limits, permissions and timestamped logs.
• LOGIN_TIMEOUT means the 15-minute interactive step expired. Start a fresh attempt.
• AUTH, IDENTITY, CATALOG or ACCOUNT_MISMATCH means Twitch validation failed. Keep the same account throughout the attempt, check Twitch Drops access and retry.
• CAPTURE_TIMEOUT, SDK_TIMEOUT and other SDK_* errors can require a new login or recovery from a Twitch/network outage. Do not edit saved credential files.

The dashboard’s connection indicator confirms access to TDM, not Twitch login. A cleanup error can occur after a session was saved; check the current login before retrying. Report the fixed code, image/source version and redacted logs, never the browser profile, session file, password, verification code or OAuth headers.

Twitch says the browser is not supported

If the message appears inside a working embedded browser, Twitch is rejecting that browser's sign-in. Changing the browser used to view the dashboard does not change the Chromium browser running inside the container.

After checking the timezone and host clock, you can select Use desktop helper on the sign-in screen and use a native browser on your own computer. Update the miner and download its matching Windows, Linux, or macOS helper. Follow the desktop helper steps; the helper needs only the dashboard URL. Access opens for ten minutes and accepts the first helper. Select Return to embedded browser to cancel it or start over after expiry.

The helper is an alternative sign-in path, not a guarantee that Twitch will accept the login. If it cannot connect to TDM, check that its URL is reachable from the helper computer and that the access window is still open. localhost points to the helper computer itself. If the helper reports an unknown result, check the dashboard before trying again. Keep saved credentials and browser profiles private.

Helper login error codes

Update both the miner and the helper to use the latest diagnostics. Known validation failures preserve their fixed SESSION_* code; unknown responses remain generic. SESSION_CATALOG means Twitch's inventory or campaign response failed validation. The miner log records only fixed error categories and field shapes, never response values or credentials. A catalog error does not by itself identify a browser rejection. Report the code and a timestamped, redacted log excerpt. Keep browser profiles, session files, cookies, tokens and passwords private.

TDM also prints a SESSION_DIAGNOSTIC JSON line after the translated helper explanation. A matching diagnostic is available as helper.diagnostic, browser.diagnostic or renewal_diagnostic in /api/session. Published helpers need a release containing this update; updating only the miner does not update the helper executable on your computer.

Field	Meaning
code	Fixed failure code, without the displayed SESSION_ prefix
stage	The step that failed; see below
reason	A fixed failure classification such as integrity, headless_fallback, timeout, tls, connection, or catalog_shape; unknown means the available response does not establish a specific classification
operation	identity, Inventory, Campaigns, or catalog when known
http_status	The dashboard/helper protocol HTTP response status, when received
upstream_status	Twitch's HTTP response status, when known; this is separate from the dashboard status

For example, code=CATALOG, stage=captured_validation, reason=integrity, operation=Campaigns identifies Twitch's integrity rejection while checking the original captured session. The same code at issued_validation means the independently issued server session failed. The original session is still not installed in either case. reason=headless_fallback at issued_validation or renewal_validation means Twitch rejected a proof issued by the headless renewal browser. This identifies the browser mode and rejection together; it does not establish why Twitch rejected the proof. On a Linux source installation, install xvfb and xauth (Debian/Ubuntu: sudo apt install xvfb xauth), or use Docker. Renewal retries pick up the change; after a failed sign-in, sign in again. Other useful stages are:

Stage	What to check
helper_configuration, helper_connect	Dashboard URL, --ca-file certificate or --insecure address, reachable miner, enabled helper window, matching versions
browser_start, browser_login, browser_capture, browser_cleanup	Helper desktop browser startup, manual sign-in/closing its windows, capture, or cleanup
helper_admission, seed_validation	Helper access or the captured context's format and freshness
server_issuance, renewal_issuance	The miner's SDK/browser acquisition step
issued_validation, renewal_validation	Twitch validation of the newly issued context
persistence	Saving private session state; retain the existing data mount and check its permissions/free space
session_upload, helper_receipt	Upload or receipt transport; check the dashboard before retrying an unknown result

The error code remains useful when reason=unknown; no arbitrary Twitch response or exception text is copied into the diagnosis. An unknown receipt result does not prove that the session was rejected or installed. TDM checks receipts and never repeats a credential upload automatically.

Twitch's visible "browser not supported" page occurs during interactive sign-in and can precede any captured session. browser.state=sign_in, browser.error=null, and session.state=waiting therefore do not establish a capture or validation error. For a helper failure, include its fixed diagnostic line, miner/helper versions and attempt time. This separates browser-side symptoms from original-session validation, server issuance, reissued-session validation and transport/storage failures. It does not establish why Twitch rejected a browser or guarantee that a new login will work.

Startup fails while reading web_auth.json

A traceback from WebAuth.__init__ ending in JSONDecodeError identifies malformed local dashboard-password state in data/web_auth.json. This is separate from settings.json, drop history and Twitch authentication. Startup deliberately stops to avoid silently disabling password protection.

Stop the miner and restrict access to its dashboard port. Restore a known-good private backup of web_auth.json, or follow the local password recovery procedure to reset only dashboard protection. Keep any malformed backup private and preserve cookies.jar, imported-session.json and all other data. Set a new dashboard password before restoring remote access. Do not attach the authentication file to an issue. If it happens again, report whether the file was edited or copied, any interrupted writes or storage errors, and whether multiple miners share the data directory.

TDM needs a new login after an upgrade

Preserve the data directory and cookies.jar. Valid Android and browser sessions are restored. Smart TV sessions from v1.3.1/v1.3.2 and expired sessions require the dashboard browser. Deleting all data is unnecessary.

Renewal is retrying or asks for another login

Temporary renewal failures are retried automatically. If TDM shows the sign in browser, complete login and verification again. Revoked access or credentials that expired during a long outage cannot always be renewed. Keep the persistent data mount and check Chromium availability, timezone and network connectivity.

The interactive browser closes after verification. Only the dashboard port is needed for login and renewal. See Automatic renewal.

No campaigns or no progress

If TDM 2.2.0 says it is watching but Twitch inventory does not advance, update to 2.2.1 or newer while preserving your data directory. The patch restores segment watch requests without downloading stream audio or video. A Watching label or accepted telemetry alone does not establish progress; compare with Twitch inventory.

Check the campaign on Twitch and work through these conditions:

1. The Twitch account is linked to the correct game account and is eligible for the campaign.
2. The campaign and individual reward are active, and the reward is earned by watching rather than by subscribing or making a purchase.
3. The game is in Settings → Games → Mining list, and its reward type is ticked in Settings → Mining → Reward types.
4. Your ignored keywords do not exclude the reward or one of its prerequisites.
5. An eligible participating channel is live. Some campaigns work only on a fixed list of channels.
6. You are not watching Twitch manually with the same account at the same time.

Higher-priority games may take precedence. If Manual Mode is active, use Return to Auto Mode to follow your normal game priorities. Upcoming or sequential rewards in the queue may need to wait for their start time or earlier rewards.

For Special Events or IRL, keep the campaign's category in Mining list; its participating channels may be streaming another category. See channel selection.

Try Reload Campaigns in Inventory or Settings → Games after correcting settings. Settings → Account & Maintenance → Clear All Cache can rebuild local campaign and channel data while keeping login, settings, and dashboard protection. It cannot repair inaccurate campaign information supplied by Twitch.

TDM excludes channels when Twitch reports any active ban for your account, including temporary bans. A temporary ban stops excluding the channel at Twitch's reported expiry; otherwise a subsequent discovery or Reload Campaigns must confirm that the ban is gone. Missing ban information does not create a ban. Clear All Cache preserves confirmed bans when a subsequent check fails, until expiry or a confirmed no-ban response. This does not override campaign eligibility or establish that Twitch will award progress.

The dashboard shows invalid_host

The browser address uses a host name the dashboard does not trust. Use the miner's IP address, set PUBLIC_BASE_URL for a reverse proxy, or add the name to ALLOWED_HOSTS. If your proxy sends its own upstream name as the Host header, add that name too. See allowed host names.

Dashboard writes or live updates fail behind a proxy

A page loading successfully does not mean its live connection or settings writes use the expected origin. Set PUBLIC_BASE_URL to the exact browser-facing root URL, including the correct scheme and any non-default port. Continue using that address.

Configure forwarded headers only for trusted proxy peers when needed. Do not set FORWARDED_ALLOW_IPS=* as a general fix. Follow the full proxy instructions.

For a temporary dashboard login request error, retry Log in. If rate limited, wait a minute before retrying. A forgotten dashboard password has a separate local recovery procedure; clearing campaign cache does not reset it.

Telegram alerts are missing

Use Test Connection in Telegram settings and check any error shown. Start a conversation with the bot before testing, and verify the chat ID. Leave a saved token's field blank to reuse it. Failed notifications are not retried and do not reverse a successful drop claim. See Telegram notifications.

Logs and reporting a problem

Save diagnosis data

Reproduce the problem and select Settings → Account & Maintenance → Dump diagnosis data. The result shows the saved JSON filename. With the supplied Docker mount ./data:/app/data, find it in your host's data/diagnostics folder; inside the container it is /app/data/diagnostics. A named volume keeps it in that same container path. Source installations use their configured data directory.

The file contains miner status, relevant settings, campaign/drop progress, channel ban results, runtime/browser details and recent sanitized API evidence. Twitch's reported minutes and local estimated minutes are listed separately. Identities, names, free text, URLs and unknown fields use aliases consistent within one file and different across files. Credentials, request headers, cookies, browser profiles, passwords, verification codes and full log messages are excluded. Warning/error locations are included without message bodies or tracebacks.

API evidence covers the miner's HTTP, GraphQL/OAuth, SDK integrity, Twitch websocket, Telegram, update-check and proxy-check paths. Capture starts during operation and resets when the Twitch account changes. Each API operation keeps its two most recent samples and a count; JSON bodies are sanitized with size and structure limits. HTML, playlists, segment data, oversized bodies and rejected authentication responses retain only metadata. Interactive browser traffic and a desktop helper's own local traffic are excluded. No stream audio or video is captured.

Dumps are saved locally; nothing is uploaded automatically. Keep the generated file alongside the reproduction steps in your bug report. Save after reproducing, before logging out or restarting. TDM retains the ten newest generated files, each at most 8 MiB. Counts and truncation markers describe omitted data. Wait ten seconds between saves. If saving fails, check the data volume's free space and write permissions; startup failures before the dashboard is available still need the redacted logs below.

For Docker, inspect console output with:

docker logs --tail 100 twitch-drops-miner

File logs are written to logs/TDM.log; the supplied Compose configuration persists that directory. A custom docker run needs a ./logs:/app/logs mount to retain those files outside the container.

Before opening an issue, search for an existing report and read CONTRIBUTING.md. Include the TDM version or source revision, installation method, operating system, relevant browser, steps, expected and actual results, and troubleshooting already attempted. For campaign issues, include public campaign/channel identifiers and the time with timezone.

Share only relevant, redacted log excerpts. Never share cookies.jar, imported-session.json, web_auth.json, a whole data directory, passwords, session cookies, or Telegram bot tokens. Support is best-effort for personal installations on your own hardware and home network.

All guides