Skip to content

Troubleshooting

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

License not found

╭──────────────────────────── 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

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

If you don’t have a license yet

# Creates/obtains a trial license interactively
werk24 init

Note

Werk24 requires a license. Use werk24 init for a trial, or contact us to provision a full license.

Still failing? Try this checklist

  • You’re using Python 3.10–3.13 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

╭──────────────────────────── 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

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:
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.