Skip to content

Troubleshooting

This page covers two common setup blockers: license not found and WebSocket connection failed.

License not found

1
2
3
╭──────────────────────────── Network Information ─────────────────────────────╮
│ License Status:  Not Found                                                   │
╰──────────────────────────────────────────────────────────────────────────────╯

Werk24 looks for a valid license file in several default locations and prints the search paths at INFO log level.

Quick fix

1
2
# Show where Werk24 is searching and why it failed
werk24 --log-level info health-check

If you don’t have a key yet

Create one in the console and store it with werk24 init or W24TECHREAD_AUTH_TOKEN, as described in Get an API key. The key is self-serve; only a contract goes through us.

1
2
# Paste the key from the console's Keys page (option 1)
werk24 init

Note

werk24 init saves the key to .werk24 in the folder you run it in. A script started from another folder does not find it; set W24TECHREAD_AUTH_TOKEN instead (a license file, where one is found, wins over it). A key the API refuses is covered under 401 Unauthorized.

Still failing? Try this checklist

  • You’re using Python 3.10–3.14 and the correct virtual environment.
  • The user running werk24 has read access to the license file.
  • The license file isn’t empty or corrupted (re-run werk24 init).
  • The log output lists the expected search directories.

WebSocket connection failed

1
2
3
╭──────────────────────────── Network Information ─────────────────────────────╮
│ WebSocket Connection (wss://ws-api.w24.co/v2):  Not Successful               │
╰──────────────────────────────────────────────────────────────────────────────╯

Many corporate networks block or intercept WebSocket (WSS) traffic by default.

What to try first

  • Run werk24 health-check off VPN/proxy (e.g., mobile hotspot) to confirm it’s a network policy issue.
  • Ensure general outbound HTTPS is working from the same machine.

If it’s your corporate network, send this to IT

1
2
3
Please allow outbound WSS (WebSocket over TLS) on port 443 to:
  wss://ws-api.w24.co  (or our regional endpoint)
If SSL interception is enabled, exempt this host or ensure the trusted CA chain is current.

Troubleshooting tips

  • Handshake/timeout errors usually indicate blocked WSS or SSL interception.
  • Some proxies require explicit WebSocket pass-through on port 443.
  • After changes, run:
1
werk24 health-check

Need more help?

  • Re-run with verbose logs: werk24 --log-level debug health-check
  • Share the last 20–30 lines of output with our support team to speed up diagnosis.