Skip to content

Troubleshooting

Before working through the entries below, open Management → Status Check. It tests DNS, cache reachability, and whether recent downloads used the cache, and it will often name the problem outright.

Logs aren't processing

  1. Check the log path under Management → Logs & Cache → Log Processing.
  2. Confirm your volume mount lines up with LanCache__LogPath.
  3. Choose Process All from the Actions menu on that same page.
  4. Look at the container logs: docker logs lancache-manager.

The web UI says "No log sources" (but the log file exists)

Point LanCache__LogPath at the directory holding access.log (e.g. /logs); the full file path /logs/access.log works too, because LANCache Manager always reads the file named access.log in that directory. A log under any other filename is not picked up. Confirm:

  1. Your volume mounts the host log directory into the container (e.g. - /host/path/lancache/logs:/logs).
  2. LanCache__LogPath points at the file at that container path (/logs/access.log).
  3. The file is readable from inside the container: docker exec -it lancache-manager cat /logs/access.log | head.

Network shares (NFS/SMB) are fine. A trailing + in ls -la output (e.g. -rw-r--r--+) is an NFS ACL marker. It does not block reads. If cat prints the file, permissions are not the problem and the configured path is what to check.

Cache size / disk usage isn't showing on the dashboard

LanCache__CachePath must point at the directory that directly contains the hashed cache folders (named like 00, 1a, ff), not its parent.

A standard lancache (monolithic) layout nests the content one level down. If you mount your cache data directory to /cache, the actual folders usually live at /cache/cache - so set LanCache__CachePath=/cache/cache. Point it one level too high and the dashboard shows the drive but reports no cache usage. Network-mounted (NFS/SMB) caches behave the same.

Check what is at the path:

docker exec -it lancache-manager ls /cache
# you should see the hashed folders (00, 1a, ... ff), not a single "cache" folder

Games aren't being identified

Steam:

  1. Refresh the mappings: Management → Schedules, find the Steam Game Mapping row, and hit Run Now (the play icon at the end of the row).
  2. Add custom mappings for any private depots you care about.
  3. Re-import the history: in Logs & Cache, choose Reposition from the Actions menu on the Log Processing card to move the read position back to the start, then process again. Already-processed entries are skipped automatically, so reprocessing is safe.

Epic:

  1. Choose Login with Epic Games under Management → Integrations.
  2. Go to Management → Schedules, find the Epic Game Mapping row, and hit Run Now. The mapping service queries the Epic API to identify what's in your cache.
  3. Game names and cover art come down automatically.

Lost API key

# from the host, if /data is bind-mounted (the default docker-compose.yml)
cat ./data/security/api_key.txt

# from anywhere, reading straight from inside the container (also works with named volumes)
docker exec lancache-manager cat /data/security/api_key.txt

On Windows Git Bash, prefix the docker exec form with MSYS_NO_PATHCONV=1 (MSYS_NO_PATHCONV=1 docker exec lancache-manager cat /data/security/api_key.txt) or the path gets rewritten to a local Windows path.

Later container restarts print the file path and a short hint, not the full key. The full key is written to the logs only when it is first created or after you rotate it.

To rotate the key, stop the container, delete ./data/security/api_key.txt, and start it again.

Forgotten main administrator password

The password can be reset without deleting the database or account. On the host, run ./data/scripts/reset-main-admin-password.sh. Password Recovery covers other container names, Unraid, and source installs.

Permission issues

Make sure PUID and PGID match the owner of your cache and log files:

ls -n /path/to/cache

Prefill won't run

The checklist is the same for all five platforms. Work down the list:

  1. Confirm the Docker socket is mounted.
  2. Confirm you're signed in as Primary or Account.
  3. Look in the container logs for the network diagnostics block (═══ PREFILL CONTAINER NETWORK DIAGNOSTICS ═══) - it tells you whether the container has internet and where CDN domains resolve to.
  4. No internet inside the prefill container. The container can't reach the platform's servers. Common fixes:
  5. Set Prefill__NetworkMode=bridge (works for most setups).
  6. Confirm your Docker network has outbound internet.
  7. Check firewall rules for outbound traffic.
  8. Downloads fail or error out mid-run. Often the container can't resolve CDN domains to your cache. The most reliable fix is Prefill__LancacheIp=<your-cache-ip> - it bypasses DNS entirely for CDN traffic. The full decision table (and what LancacheDnsIp/NetworkMode do instead) is in Network setup.
  9. IPv6 traffic bypassing DNS. If your network has IPv6, queries can bypass lancache-dns. LANCache Manager disables IPv6 inside bridge-mode prefill containers to prevent this; Docker doesn't allow that with host networking, so a host-mode container needs IPv6 handled at the network level instead.
  10. Epic sign-in never completes. Open Epic's sign-in page, sign in there, and paste the code into LANCache Manager. The login is kept with the prefill container. A persistent container can stay signed in across a LANCache Manager restart when After a restart keeps it. A temporary session starts signed out.

To find the IP of your lancache-dns:

docker inspect lancache-dns | grep IPAddress

A scheduled prefill "skipped" services

That's Scheduled Prefill working as designed. A scheduled run only uses a container that is already running, and for Steam, Epic, and Xbox, signed in.

To fix it:

  1. Click Start on that service in the Scheduled Prefill card.
  2. For Steam, Epic, or Xbox, click Manage and sign in.

The next run includes it. The schedule keeps its interval either way. A run is only reported as unsuccessful when no service ran at all.

Hit rate looks lower than expected after a prefill

Usually nothing is wrong - the number includes the prefill itself. The dashboard hit rate is byte-weighted across every client that touched the cache, including the prefill container (the Prometheus lancache_service_hit_ratio metrics blend the same way).

On an empty cache, a prefill run is close to 100% MISS and the install that follows is close to 100% HIT. Together, one game blends to roughly 50%. Each reinstall pushes the number toward 66%, 75%, and higher, because the MISS bytes are a fixed floor while every install adds more HIT bytes.

To keep prefill traffic out of the figures, pick one:

Option Effect
Add a rule in the Prefill traffic pane on Management → Clients Leaves prefill runs out of the figures and out of /metrics, for any address. Needs no client address. See Prefill traffic rules.
Click Add prefill rule in a client's pane on Management → Clients The same, for the prefill runs recorded with that client's address
Filter a client out in the Downloads or Dashboard client filter Hides its traffic from view. The data is not changed.

For a specific install's real hit rate, switch Downloads to the Retro view, open the settings panel, leave Group by game unchecked under Display, and check that client's own row - or grep access.log for its IP. The manager only counts literal HIT/MISS from nginx's upstream_cache_status, so it always agrees with a manual log count.

Some real misses are normal even on a clean install:

  • the prefill daemon only grabs Windows/x64/English depots by default
  • an interrupted earlier run without --force leaves gaps
  • HTTPS/IPv6 traffic that bypasses lancache-dns never touches the cache

Prefill traffic rules

Prefill rules are set on the Management → Clients page, in the Prefill traffic pane (rules for Any address) or in a client's pane (a rule added with Add prefill rule, listed under Stats below the All traffic row). A prefill rule matches only downloads the manager marks as coming from a prefill run. Each pane has its own Save; nothing changes until you click it.

Rule field Choices
Address One client address, or Any address, which Add prefill rule creates. A rule with no address can only be a prefill rule.
Services All services, or any of Steam, Epic Games, Xbox, Battle.net and Riot. Only a prefill rule picks services.
Mode Hidden or Stats only, the same two modes as an all-traffic rule.

A prefill rule handles the downloads it matches like this:

Mode Left out Kept
Hidden Total served, bandwidth saved, the hit ratio, client counts, active downloads, the Downloads list and its 24-hour history, and /metrics Added to cache
Stats only The dashboard figures and /metrics The Downloads list, live speeds and Added to cache

With a prefill rule saved, Total served no longer equals Saved plus Added to cache.

  • Marking runs all the time, with or without a rule. Prefill runs recorded before this install was updated to record run addresses keep counting.
  • A prefill rule applies to every run recorded with an address. New runs are covered within one log read. After an update, earlier runs are marked oldest first as new log lines are read, so for the first minutes some older runs can still count. A cache that logs nothing marks nothing until it logs again.
  • A prefill rule for an address still lets you add an all-traffic rule for the same address.
How prefill runs are recognized

When a prefill run starts, it sends one small request (/lancache-heartbeat) to the cache it downloads from. The manager records the address the cache logged for that request as the run's address, and marks downloads from that address, for the same service, during the run.

Setup Recognized
Host mode (the cache logs the daemon under its LANCACHE_IP address) Yes
Bridge mode, on the same Docker network as the cache or another one Yes
Host-mode prefill with a bridge-mode cache Yes
Docker Desktop Yes, through a shared address (see below)
macvlan or ipvlan Yes
Rootless Docker, Podman Yes
A proxy in front of the cache that passes X-Forwarded-For Yes
A cache on another machine whose log this manager reads Yes, through a shared address (see below)

When the run's address is shared with other devices, only the run's time window and service separate prefill traffic from other traffic, so another device downloading the same service during a prefill is counted as prefill. Docker Desktop logs every device behind a published port under one gateway address, and a cache on another machine sees the Docker host's address for every container on it.

These runs are not recognized and keep counting:

  • Runs recorded before this install was updated to record run addresses. The help on the Prefill traffic pane gives the start of the last of them.
  • Bridge runs from before this update whose Docker network no longer exists. The update rewrites older bridge runs to the gateway of the Docker network that holds their stored address; a run whose network is gone is left as it was.
  • A run whose start request failed. The daemon log names the failure.
  • A run whose start request was answered by a cache whose log this manager does not read. Nothing is logged where the manager looks; check that the cache's log is a datasource of this manager.
  • A run whose start request was answered by a proxy that answers /lancache-heartbeat itself. The cache never sees the request, so nothing is logged.
  • Runs from prefill images older than this release are recognized only as before: in host mode, and in bridge mode where the cache logs the container's own address.

Debug logging

Turn this on when path auto-detection fails, prefill containers won't spawn, volume mounts look wrong, or you're on an unusual platform:

environment:
  - Logging__LogLevel__LancacheManager.Infrastructure.Platform=Debug

You'll get extra detail on:

  • Path resolution (container vs host paths)
  • File system operations and permission checks
  • Docker socket communication and container detection
  • Volume mount detection
  • Linux/Windows platform differences

To use it: add the variable, restart with docker compose up -d, reproduce the issue, then check docker logs lancache-manager. Remove the variable when you're done - it's noisy.