Skip to content

Troubleshooting and FAQ

Jump to bottom
60plus edited this page Jul 7, 2026 · 1 revision

Troubleshooting & FAQ

Practical fixes for the problems you are most likely to hit, plus answers to the questions people ask most often. If something here does not solve it, grab the container logs (see First stop: logs and health) and ask on the Discord community.

Contents

First stop: logs and health

Almost every issue is diagnosable from the container logs. Follow them live:

docker compose logs -f gamesdownloader

Check whether the API is up with the health endpoint (it returns HTTP 200 once the app has finished initialising):

curl http://localhost:8080/api/health

You can also see container health at a glance with docker compose ps (look for healthy, starting, or unhealthy in the status column).

Troubleshooting

The web UI is unreachable for a minute after first start

Symptom: right after the first docker compose up, http://localhost:8080 does not load, and docker compose ps may briefly show the container as starting or unhealthy.

Cause: on first boot the app fetches and parses a large (~150 MB) LaunchBox metadata archive and builds its on-disk index before the API binds. This can take 60 to 90 seconds. The Compose file gives the health check a 120 second start_period precisely so the orchestrator does not kill and restart the container while it is still initialising.

Fix: wait it out. Watch progress in the logs:

docker compose logs -f gamesdownloader

Once you see the API listening and curl http://localhost:8080/api/health returns 200, reload the page. This delay only happens on the first boot; the LaunchBox index is cached under data/config/launchbox_cache and reused on later starts.

The initial parse is a one-time cost. If the container is still unhealthy well past two minutes, capture the logs and check for a database or Redis connection error rather than assuming it is the LaunchBox step.

ClamAV is not scanning

Symptom: uploads or GOG downloads are not being virus-scanned, or the ClamAV status shows the daemon is not running.

Cause: the virus definition database is not bundled in the image. Until it is downloaded, the ClamAV daemon has nothing to load and stays inactive.

Fix: go to Settings → Security → ClamAV and click Update Definitions to download the database (~300 MB via freshclam). The daemon starts automatically once definitions are available. Definitions persist in the data/clamav volume, so you only do this once (and whenever you want to refresh signatures).

A from-source build fails partway with a decompression or segfault error

Symptom: docker compose build dies mid-way with a decompression error, a segmentation fault, or a truncated-layer message.

Cause: this is almost always a corrupted Docker layer cache, not a bug in the project source. A partially written or damaged base/app image layer breaks the build in ways that look like a code failure.

Fix: remove the affected images, prune, re-pull the bases, and rebuild clean:

docker compose down
docker rmi 60plus/gamesdownloader:latest
docker image prune -f
docker compose build --no-cache gamesdownloader
docker compose up -d

Do not hide the build result behind a pipe. Piping build output through another command (for example docker compose build | tail) can mask the real exit code, so a failed build looks like it succeeded. Run the build on its own and read the actual exit status.

A port is already in use

Symptom: docker compose up fails with a bind or "address already in use" error, or a service will not start.

Cause: another process (or another container) already holds one of the ports GamesDownloader publishes. By default those are 8080 (web UI), 9091 (Transmission WebUI), and 51413 TCP and UDP (Transmission peers).

Fix: remap the conflicting port in your .env and bring the stack back up. The Compose file reads these variables:

Variable Default Purpose
GD_PORT 8080 Web UI / API
TR_WEBUI_PORT 9091 Transmission WebUI
TR_PEER_PORT 51413 Transmission peer port (TCP + UDP)

For example, to move the web UI to 8090, set GD_PORT=8090 in .env, then:

docker compose up -d

Files created by the container are root-owned

Symptom: files the app writes into your host data folders are owned by root, and your normal user cannot edit or delete them.

Cause: by default the container process runs as root, so anything it creates on bind-mounted volumes lands as root-owned.

Fix: set PUID and PGID in your .env to your host user's ids so the app writes files as that user. On Linux, find them with id -u and id -g. See Installation for the full setup.

I forgot the admin password

Symptom: you cannot log in and want to reset the password yourself.

Cause: the self-service Forgot Password flow sends a reset link by email, so it only works when two things are configured: a working SMTP server, and a correct Public base URL (the link in the email is built from it, so a wrong base URL produces an unusable link).

Fix: configure SMTP and set the Public base URL, then use the Forgot Password link on the login page. Both settings are covered in Network & Security. If email is not set up at all, another user who still holds the Admin role can reset your password from the admin Users panel.

A scraper Test button fails

Symptom: the Test button for a metadata source under Settings → Metadata reports a failure.

Cause: usually a wrong, expired, or mistyped API key or credential, or (for some sources) an ID and secret pair where one half is off.

Fix: re-check the key or credentials for that provider and paste them again carefully. Full per-source setup, including which sources need an ID plus a secret, is in Scrapers & Metadata.

HTTPS/HSTS is not applied behind my proxy

Symptom: you run GamesDownloader behind a reverse proxy that terminates TLS, but secure-only behaviour (HSTS and HTTPS-aware links) is not being applied.

Cause: the app decides whether a request arrived over HTTPS from the forwarded headers your proxy sends. If the proxy does not pass X-Forwarded-Proto, the app treats the request as plain HTTP.

Fix: configure your reverse proxy to send X-Forwarded-Proto (set to https on the TLS listener), and make sure the proxy's address is in the trusted proxy list so the header is honoured. Proxy configuration, trusted proxies, and the forwarded-header requirements are covered in Network & Security.

Torrents are not connecting

Symptom: torrent downloads or library seeding stay at zero peers and never make progress.

Cause: the Transmission peer port is not reachable from the outside, so no peers can connect.

Fix: expose the peer port 51413 on both TCP and UDP through your firewall (and any router port-forwarding). The Compose file already publishes 51413/tcp and 51413/udp; you just need the host firewall and network to allow it. Also confirm Transmission is enabled under Settings → Downloads → Transmission. More detail in Downloads & Torrents.

FAQ

Can I run it fully offline / LAN-only with no domain? Yes. LAN-only operation with no public domain and no reverse proxy is a first-class, fully supported mode. Point your browser at http://<server-ip>:8080 and everything works. You do not need HTTPS, a domain, or a proxy to use GamesDownloader on your own network.

Does it need internet access at all? Only for a few specific things: pulling the Docker images (or fetching build dependencies), downloading metadata and artwork from the online scrapers, and updating ClamAV virus definitions. The core library, in-browser emulation, downloads, and playback of what you already have work without any internet connection.

How do I back up my data? Everything persistent lives under GD_BASE_DIR on the host (database, config, media, plugins, ClamAV definitions, and so on), so backing up is a matter of copying that tree while the stack is stopped or the database is quiesced. See Configuration for the full volume layout and a backup routine.

How do I update to a new version? Pull the new prebuilt image (or rebuild from source) and recreate the containers; your data volumes are untouched. Step-by-step update instructions, including the Docker Hub tags, are in Installation.

Where are the logs? docker compose logs -f gamesdownloader for the live application log, and curl http://localhost:8080/api/health to check whether the API is up. See First stop: logs and health.

Next: Installation - Network & Security

GamesDownloader

Wiki Home

Getting Started

Configuration

Features

Plugin Development

Reference

Discord

Clone this wiki locally