Repository navigation
Troubleshooting
Run these from your deployment directory:
docker compose ps
docker compose logs --tail=200 tmodloaderUse dashboard Overview and Backups & recovery for health, pending changes, and recovery guidance. A running container does not by itself mean the game is ready.
From 3.7.0, Docker's container probe accepts pending admin setup while the dashboard responds. After setup, both dashboard availability and game readiness are required. With the dashboard disabled, it checks the game directly. The game probe checks the process, startup log, and TCP listener without opening player connections. A healthy container waiting for setup is not yet a playable server.
The default startup grace period is 60 seconds, with checks every 30 seconds and three retries. Keep TMOD_HEALTH_START_PERIOD=60s by default. If measured startup time exceeds the grace period, increase it as needed in .env with the current Compose template and recreate the container. An older Compose file needs the matching healthcheck.start_period override. Increasing the grace period does not fix persistent startup errors; inspect the logs. Docker's restart: unless-stopped policy does not by itself restart a running container solely because its health status becomes unhealthy.
For an unhealthy game, correct the logged cause and review Restart now on Overview. View game controls in Backups & recovery opens the same controls. Interrupted restores and active operations still prevent conflicting work.
Version 3.7.2 also includes a server-only TCP listener lifecycle fix for the listener stopping after anonymous connections fill the server. Update the container image and recreate it to receive this helper change; updating only the tModLoader runtime does not replace container components. Clients do not need to install the helper.
| Symptom | Check and next step |
|---|---|
| Game waits on first boot | With WebUI enabled, complete admin setup using the code in container logs. For game-only operation, set TMOD_WEB_ENABLED=0 and recreate the container. |
| Admin token is forgotten | Use the host-terminal reset procedure in Web dashboard. |
| Dashboard unavailable from another computer | Current Compose publishes the dashboard for LAN access. Check the host IP, published port, firewall, and whether an older Compose file still binds only to localhost. See Networking and access. |
| Dashboard says HTTPS is required | HTTP only accepts RFC 1918 or loopback source addresses. Use HTTPS for other sources, including VPN ranges outside RFC 1918. |
| Proxy requests or forwarded headers are rejected | Configure TMOD_WEB_TRUSTED_PROXY with the proxy IP or, on 3.7.4+, its resolvable service name/network alias as seen by the container. DNS failures reject forwarded headers; the proxy must overwrite the client-IP/protocol headers and preserve Host. |
| Dashboard requests fail after changing its URL | Ensure TMOD_WEB_ORIGIN matches the exact browser origin and recreate the container after changing .env. |
| First-run submission is disabled or the setup code is rejected | Complete all fields, use an 8–256 character non-whitespace ASCII token, and make both token entries match. Check the current one-time code in the container logs. |
| Settings cannot be edited or a selection cannot load | Check TMOD_CONFIG_SOURCE=web. Custom configuration mode also restricts world/playthrough operations. |
| Startup reports invalid web-managed configuration with a custom file |
TMOD_USECONFIGFILE=Yes requires environment-managed settings: disable WebUI on 3.7.3, or explicitly set TMOD_CONFIG_SOURCE=env. Use generated configuration if you want web-managed settings. |
An .env change does not change saved web settings |
Enabled web-managed mode preserves saved values. Edit and apply them in the dashboard. With WebUI disabled, 3.7.3 ignores saved settings and passwords; 3.7.2 also needs explicit TMOD_CONFIG_SOURCE=env. |
| Saved settings do not affect the running game | Review and apply the draft, then wait for confirmed healthy startup. |
| World evil, size, or seed appears unchanged | Generation settings only affect new worlds. Choose an unused world name. |
| Workshop search asks for a key | Search needs a Steam API key validated on Workshop or supplied through a mounted file; URL/ID lookup does not. See Mods and Workshop. |
| Runtime update is blocked or startup takes longer | Read Overview update diagnostics and compatibility-test logs. Check free data-volume space, Steam/download access, supported release selection, and the test timeout. Failed checks retain the selected runtime and live mods. See Runtime updates. |
| First startup cannot install tModLoader | Since 3.5.0 no runtime is bundled. Check internet access and writable space in /data; TMOD_AUTO_UPDATE=0 does not skip the initial download. Retain the persistent data volume for later starts. |
| Player history is empty or lacks addresses | Tracking starts with 3.5.0; earlier visits are not reconstructed. Check /data/.tmod-control/character-bridge/build.log for helper failures. English join announcements can provide name-only fallback history. A name alone cannot support an offline ban. |
| History ban did not disconnect a player | History bans block future connections. Use Kick under Connected players for an existing session; verify the resulting player state. |
| Game version changed despite a pinned image | Startup runtime updates default to enabled. An image pin does not pin the selected runtime; review TMOD_AUTO_UPDATE and TMOD_UPDATE_VERSION. |
| Runtime update rolled back or recovery is queued | Follow the checkpoint status and confirmed recovery controls in Overview. Do not delete recovery material to force startup. Automatic updates remain held after recovery until explicitly resumed. |
| Mod config save reports a conflict | Compare your edits with the latest disk version, then choose disk, keep your draft, or combine edits. Invalid disk JSON needs syntax repair before comparison. See conflict recovery. |
| Review & save is disabled | Open a file and make a content change; identical content or line-ending changes alone do not enable saving. Resolve syntax errors before saving. |
| A mod configuration file is missing from the editor | Let the mod generate it, then Refresh files and clear search/location filters. Only existing supported files under tModLoader are offered; saves, logs, installed mods, and tModLoader settings are excluded. |
| Profile config restoration is blocked | Files must exist and must not have changed since loading the profile. Preserve newer disk edits, generate missing configs with their mods, then reload and review the profile; or load only its Workshop selection. |
| Workshop key stops working after an admin-token reset | Re-enter and validate the Steam API key on Workshop. |
| World deletion is unavailable | Running and draft-selected worlds are protected; switch worlds and review or cancel the saved draft first. |
| Mods fail while Steam is unavailable | Inspect download errors and offline policy. use-cache needs existing cached content; strict fails required update checks. |
| Players cannot connect | Verify healthy game startup, compatible client version/mods, host TCP port publishing, firewall, and router forwarding. |
| Backup fails before stopping the game | Check writable backup storage and available disk space against TMOD_BACKUP_MIN_FREE_MB. |
| Restore rejects a build mismatch | Inspect the archive. If the tModLoader release matches, use Prepare for Running Container Version and inspect/restore the new copy. Otherwise use the original image build. |
| Backup inspection fails | Read the error beside the archive, check that both bundle files exist and storage is accessible, and retry after fixing the cause. Keep the original archive. |
| Journey controls are missing | Controls appear for confirmed Journey worlds only. Unsupported headers or other difficulty modes do not show them. Manage permissions on Worlds, not Configuration. |
| World total uptime is lower than expected | Tracking starts with the new feature and counts loaded server time, not historical sessions or player playtime. Inactive worlds retain totals but have no current-session uptime. |
| Interrupted restore blocks startup | Preserve restore-pending and recovery originals; follow Backups and recovery. |
| Persistent folders report permission errors | Check mount paths and whether the host filesystem permits startup ownership repair to UID/GID 1000:1000. |
docker compose exec --user tml:tml -T tmodloader inject "save"Check the console for completion. This updates the live world; use a backup to create an archive.
Set TMOD_LOG_LEVEL=debug in the active configuration source and apply the change. In environment mode, recreate with docker compose up -d; in web mode, save and apply through Configuration. Return to normal after investigating if you prefer less console output.
Raw console output is retained at /data/tModLoader/Logs/container-console.log, which is ./data/tModLoader/Logs/container-console.log with the supplied Compose mounts. Dashboard console history also provides retained console runs. Inspect these when the displayed Docker log excerpt omits the failure details.
In 3.8.0, open Overview → Get help → Preview support report. The report includes container and tModLoader versions, settings mode, enabled mods, and recent error lines. If startup has not completed a confirmed mod load, it distinguishes enabled filenames from confirmed loaded mods. Recent errors are a bounded excerpt, so they may not include the full failure.
Sensitive values and private log details are removed before the preview reaches your browser. Review the editable report and remove any remaining private details, then choose Copy report. Open bug report template opens the issue form; paste into its optional Dashboard support report field and describe what happened. The dashboard does not submit anything automatically. If clipboard access is unavailable, use your device's Copy command on the selected report text.
A repository-provided 3.8.0 preview with demonstration mod and error data. Select the image to view full size.
If the dashboard is unavailable or your image predates support reports, collect logs using Start with status and logs and the persistent console log described above. Add log excerpts around the failure when the report omits them.
Include the image tag or digest, actual selected tModLoader runtime, update/recovery status, host architecture, game readiness/status, relevant logs, configuration mode, and steps that reproduce the issue. Remove passwords, admin/setup tokens, API keys, and other private information before sharing.
Open a bug report. Follow the project's security reporting instructions for vulnerabilities.
If a schedule does not run, check Configuration → Scheduling, the saved-change review, game health, and active backup or administration work. Saved drafts must be applied. Calendar times use the configured timezone; Overview displays the next restart in your local time. A restart warning starts at the scheduled time, then waits the configured delay.
Console archive defaults are 30 days and 512 MiB; setting either limit to 0 disables that limit. Active console output rotates at 64 MiB by default (TMOD_LOG_ROTATE_MB, 1–1024). Current and previous console logs, game logs, and player history are excluded from archive cleanup. Keep separate copies when longer-term diagnostics are needed.