Repository navigation
Troubleshooting
Common problems, their causes, and how to fix them. For install steps see Installation; for client data paths see Client Setup & Usage.
| Component | Location |
|---|---|
| Client (Windows) | %APPDATA%\gsbs\gsbs.log |
| Client (Linux) | ~/.config/gsbs/gsbs.log |
| Server (Docker) | docker compose logs gsbs |
| Server (binary) | stderr / GSBS_LOG_LEVEL=debug
|
Set GSBS_LOG_LEVEL=debug on the server or client for structured diagnostics. Add "verbose_log": true to client config.json for per-file push/pull detail.
Usually a stale Docker image or missing embedded templates from a source build.
- Pull the latest image:
docker compose pull && docker compose up -d - Or rebuild from source: run
./script/build-webui.shbeforego build ./server
- Set
GSBS_SESSION_SECRETto a long random value (openssl rand -hex 32) and restart the container. - Behind a reverse proxy: ensure the proxy forwards
Host,X-Forwarded-Proto, and cookies. SetGSBS_TRUST_PROXY=1on the server.
- Admin → PCGW: check the last sync run status and any errors.
- Manually trigger a sync: Admin → PCGW → Incremental Sync (routine) or Auto Catch-Up (large backlog).
- Check
GSBS_PCGW_CRONis not set to""(disabled).
- Check Dead-letter on the PCGW status card. If non-zero, run Reset Dead Letter (Advanced Maintenance), then Auto Catch-Up.
- Use Parse Missing Only to ingest never-fetched catalog IDs without a catalog refresh.
- Use Retry Failed Pages for
failed/partialrows only. - If the page budget is exhausted mid-run (
GSBS_PCGW_MAX_PAGES_PER_RUN, default 5000), run Incremental Sync again or Auto Catch-Up to continue. - Full Reparse (Advanced Maintenance) forces a full catalog rescan and re-processes backlog plus wiki-changed pages — rarely needed.
docker compose logs gsbs
docker compose psCommon causes:
-
GSBS_DBpoints to a path not on a mounted volume (container can't write it). - Incorrect volume permissions. The entrypoint fixes
/app/dataownership on startup. -
GSBS_SESSION_SECRETis unset (server will not start without it in newer builds).
- Check server logs for
error_class(e.g.db_locked,schema_error). - If
db_locked: SQLite is under contention. Reduce concurrency or check for another process holding the DB. - If
schema_error: the DB migration may be incomplete. Review the startup log for migration status. - Dashboard partials show an inline HTMX retry notice on store errors — the page remains usable while the underlying issue is resolved.
Clients receive 429 when they exceed per-user or per-IP rate limits. Defaults are generous (120 pushes/min per user). If you hit them legitimately, adjust GSBS_RATE_LIMIT_PUSH or similar.
The tray is pure-Go D-Bus (StatusNotifierItem) — no appindicator libraries are needed, but your desktop must run an SNI host:
- GNOME: Install the AppIndicator and KStatusNotifierItem Support extension (GNOME has no built-in tray).
- KDE / Xfce / Cinnamon: Usually works out of the box.
-
xdg-utilsis used for opening links (sudo apt install xdg-utils/sudo dnf install xdg-utils).
Run gsbs-client --console to verify the client starts correctly without a tray.
The sandbox grants home, the default Steam/Heroic/Lutris/Bottles data dirs, and /run/media (SD cards). A Steam library on another internal drive (e.g. /mnt/games) is invisible until you grant it:
flatpak override --user io.github.dlommm.GSBS --filesystem=/mnt/gamesor add the path in Flatseal → GSBS → Filesystem, then restart the client. GSBS shows a one-time "limited access" notification when it detects a blocked save folder.
The client stores tokens in the Secret Service keyring. On systems without one, fall back to an on-disk token:
flatpak override --user io.github.dlommm.GSBS --env=GSBS_TOKEN_STORE=fileBy design — sandboxed installs update via flatpak update or your software center, not the in-app updater.
Token expired or revoked. To resume:
- Open tray Login… or run
gsbs-client login. - If the token was revoked: create a new API token in WebUI Settings → API tokens.
Version note: Password changes and 2FA disable now revoke all active client tokens automatically. After a credential change, you must log in again on every client.
When the server returns HTTP 401, the outbox stops retries immediately via the ErrUnauthorized sentinel. If the local status page shows auth_failed: true, simply re-login to resume.
If you see repeated 401 errors after re-logging in, verify the token has not been revoked: WebUI Settings → API tokens.
- Confirm games are installed via a supported launcher (Steam, Epic, GOG, Ubisoft Connect, Heroic, Lutris, Bottles, Prism Launcher, or Flatpak Steam).
- Set launcher folder overrides in
config.jsonif auto-detect fails (e.g.heroic_folder,steam_library_folders). - Tray → Rescan installed games to re-run discovery immediately.
- Check
discovery.jsonandgsbs.log(look for launcher detection logs).
Check the tray Discovered games list for the per-game readiness reason:
| Tray label | Cause | Fix |
|---|---|---|
⚠ not in server manifest |
no_manifest_entry |
Run PCGW sync on server, or use Add a game manually… |
⚠ no saves for this OS |
wrong_platform |
Use Add a game manually… with your local folder |
⚠ save folder not found |
save_dir_missing |
Launch the game once so its folder exists, or set game_install_paths in config |
⚠ no valid save rule |
malformed_rules |
Fix the manifest entry on the server |
⊘ <game> |
disabled |
Click to re-enable, then Refresh manifest |
Advanced diagnostics:
gsbs-client debug-sync <game_id> --dry-runPrints readiness reason, resolved watch dirs, path_key, and files that would upload — without sending any data.
Also check:
-
sync_pausedis nottrueinconfig.json. - The outbox (
outbox/directory) does not contain stale undeliverable entries. -
GSBS_LOG_LEVEL=debugshows detailed sync logs withgame_id,path_key, andrelative_path.
Two Windows-specific edge cases:
-
fsnotify overflow: If the OS event queue overflows during many rapid file changes, the client now triggers a directory rescan to catch missed events (look for
watcher_overflow_rescanin the log). -
Locked files: Files held exclusively by the game during push retries are now enqueued to the outbox instead of dropped (look for
push_locked_file_enqueuedin the log).
If saves still don't upload: check outbox/ in the client data directory and gsbs.log for either log op above.
Clients try GET /api/manifest/v2 first, then fall back to v1. If manifest fetch consistently fails:
- Confirm the server URL is correct in
config.json. - Confirm the client token is valid (
gsbs-client loginif in doubt). - Delete
manifest.jsonin the client data directory to force a full re-fetch on next run (rarely needed). - Check server logs for manifest handler errors.
- Look in
gsbs.logfor lines prefixed withupdate:(e.g.update: check result status=network_error). - Possible statuses:
available,up_to_date,disabled,metered_skip,network_error,api_error,manifest_mismatch,unsupported_arch. -
metered_skipon Windows: connection is metered andskip_sync_when_meteredis true — switch to an unmetered connection or disable the setting. -
api_errorornetwork_error: check GitHub reachability andupdate_repovalue in config.
All upgrade troubleshooting is covered in Upgrading. See:
# Client readiness for a specific game
gsbs-client debug-sync <game_id> --dry-run
# Force-push all matched files for a game (requires login)
gsbs-client debug-sync <game_id>
# Show what the client is syncing
gsbs-client list
# Check server health
curl https://your-server/api/health
curl https://your-server/api/health?ready=1- Reproduce with
GSBS_LOG_LEVEL=debugenabled on both server and client. - Search GitHub Issues.
- For security concerns, see Contributing → Security.
Since 4.0.0, 2FA secrets are encrypted with a key file kept next to the database (gsbs-keys/totp.key). Restoring the DB without that file makes TOTP fail closed. Restore gsbs-keys/ from the same backup, or disable 2FA for the user directly in SQLite and re-enroll:
sqlite3 /path/to/gsbs.db "UPDATE users SET totp_enabled = 0, totp_secret = '' WHERE username = 'NAME';"Expected since 4.0.0: a fresh device that pushes a save which already exists on the server with different content records a conflict instead of overwriting it. Resolve from the tray (Conflicts → Keep local / Use server) or the WebUI.
Getting started
Reference
Help
Contributing