Skip to main content

Troubleshooting

Start with the checklist below. If the problem persists, collect a complete log file and ask for help on Discord or in the GitHub issue tracker.

Before you ask for help​

  1. Check that the server is running and reachable from the client.
  2. Restart the client and the server.
  3. Set SERVER_LOG_LEVEL to debug and read the logs.
  4. Verify your configuration, volumes and permissions.
  5. Reproduce the problem once and note the exact time.

Include the GameVault version, the client platform, the server image tag and a complete log file. Never paste secrets; replace them with **REDACTED**.

The client cannot connect​

  • Use the correct protocol. A server without TLS needs http://, not https://.
  • Confirm the port. The default is 8080; a reverse proxy may expose 443.
  • If the server is behind a proxy, verify that the proxy forwards WebSocket upgrades and does not buffer large downloads.
  • A 500 response usually points to a server-side problem. Check the server logs before changing client settings.

The first admin account does not work​

Register the first user after the server starts. The first registered account is activated automatically and receives the admin role. If you already created users, see admin role recovery and admin password recovery.

Permissions denied / EACCES​

GameVault runs as a non-root user (1000:1000 by default). The container user must be able to read and write every mapped volume:

  • game files (VOLUMES_FILES)
  • media (VOLUMES_MEDIA)
  • save files (VOLUMES_SAVEFILES)
  • logs (VOLUMES_LOGS)
  • the SQLite database (VOLUMES_SQLITEDB)

Either grant the correct permissions on the host or set PUID and PGID to a user that owns the folders. Do not run the container as root.

Symptoms include failing media saves, an empty or unwritable SQLite database, indexing errors and EACCES messages.

Games do not appear​

GameVault 2 library with an empty installed section and two active filter chipsActive filters stay in place until you clear them

Missing box art or metadata​

  • Configure a metadata provider.
  • Check that the provider is enabled in the server configuration.
  • Verify the file names; ambiguous names cannot be matched reliably.
  • A (NC) flag on any version file disables provider updates for the whole game. Remove the flag and trigger a refresh.
  • Clear the media cache in the client and reload the library.

Incorrect game mapping​

Remap the game in the client: GameVault 2 or GameVault 1.

Slow downloads​

  • Remove the client bandwidth limit under Settings → Downloads in GameVault 2 or Settings → Installation in GameVault 1.
  • Remove the server limit: unset SERVER_MAX_DOWNLOAD_BANDWIDTH_IN_KBPS or set it to 0.
  • Make sure the client is using the LAN address, not the public address.
  • Check proxies, VPNs and older network hardware between client and server.
  • Restart both sides after changing limits.

How to collect logs​

  1. Set SERVER_LOG_LEVEL=debug in the server environment.
  2. Set SERVER_LOG_FILES_ENABLED=true.
  3. Map a host folder to /logs (Docker) or set VOLUMES_LOGS (native).
  4. Reproduce the problem.
  5. Send the complete log file from server start to the error. Do not trim it.
Complete logs are required

Trimmed logs hide the cause. Redact secrets with **REDACTED**; the server redacts most sensitive values automatically.

Still stuck?​