Troubleshooting

This page covers common setup and runtime issues.

WebSocket does not connect

Symptoms

  • WaitUntilConnectedAsync(...) returns false
  • no events are received

Checks

  1. Confirm League Client is running.
  2. Verify lockfile resolution:
    • set LCU_LOCKFILE explicitly, or
    • ensure automatic discovery can resolve your layout.
  3. If process inspection is permission-limited on your machine, prefer LCU_LOCKFILE.
  4. On macOS, verify default bundle locations if relying on known-path discovery:
    • /Applications/League of Legends.app/Contents/LoL/lockfile
    • /Applications/Riot Games/League of Legends.app/Contents/LoL/lockfile
    • /Applications/Riot Client/League of Legends.app/Contents/LoL/lockfile
  5. Ensure local certificate options are enabled when needed:
    • AcceptSelfSignedCertificates = true
    • WsAcceptSelfSignedCertificates = true

Linux/Wine/Proton layout issues

Why this happens

Official support targets Windows and macOS. Non-standard layouts are best-effort and may not match built-in discovery assumptions.

Fix

  • Set LCU_LOCKFILE explicitly.
  • Avoid relying on process-derived discovery in constrained/containerized environments.

HTTP request fails with 401/403

Likely causes

  • stale lockfile credentials
  • client restart while process kept old state

Fix

  • Restart your app so lockfile credentials are refreshed.
  • If using LCU_LOCKFILE, verify it points to the current lockfile.

HTTP request fails with "Unsafe absolute URI"

Why this happens

Thresh intentionally restricts LCU-authenticated absolute HTTP requests. If an absolute URI is not HTTPS loopback on the active lockfile port, Thresh rejects it before attaching credentials.

Fix

  • Prefer relative LCU paths.
  • If you use absolute URIs, ensure all checks pass:
    • scheme is https
    • host is 127.0.0.1, ::1, or localhost
    • port matches the current lockfile port

Frequent reconnects

Likely causes

  • long periods without incoming events
  • intermittent local connectivity behavior

Fix

  • Increase WsSilenceThreshold.
  • Review logs and metrics to identify message gaps and reconnect cadence.

Service provider disposal error in tests

If your tests resolve IEventStream, prefer async disposal:

await using var provider = services.BuildServiceProvider();

IEventStream implements IAsyncDisposable, so synchronous disposal can throw in strict test scenarios.

DocFX build issues

  • Ensure DocFX is installed/updated:
dotnet tool update -g docfx
  • Build docs from repository root:
docfx docs/docfx.json

If links fail, verify docs/toc.yml and docs/articles/toc.yml paths.