Troubleshooting
Reliability contract
init() may raise (missing key, version skew). Everything else degrades to warnings: dead servers cost you points, never a crashed training job. Always finish() in a finally — unflushed points and heartbeats die with the process, and the run stays RUNNING until staleness flips it.
Error model
| Situation | Behavior |
|---|---|
Missing API key at init() | RuntimeError (the one loud failure) |
| Server version incompatible | RuntimeError at init() |
Bad create_sweep space / dead sweep link | raises (ValueError/RuntimeError from the server) |
Network/server error in log() | warn after 3 retries, drop batch |
Network/server error in finish() | warn, never raise |
log() before init() / after finish() | warn, drop |
| Bad/oversize image or artifact input | warn, skip |
| Config sync failure or frozen run | warn, stay local |
init() twice | warn, finish previous run |
Common issues
RuntimeError: Missing Cursus API key
No key in arg/env/config file. The API Keys page shows your deployment URL plus a copy-paste setup block.
Fix: Set the environment variable or pass api_key= to init():
RuntimeError: Incompatible Cursus server API version
The SDK and server major versions don't match. Never mix majors.
Fix: Upgrade the SDK (pip install -U sagea-cursus) or the server.
Flat line at step 0 in charts
A log() call missed step=.
Fix: Always pass step=step to every log() call.
Run stuck RUNNING after a kill
Expected until the 15-minute stale window passes.
Fix: Use finish("crashed") in a handler for instant accuracy.
404 on init() with group=
Wrong slug, or you are not a member of that group (ask a super admin). The server never distinguishes the two.
403 on every write with a fresh key
The key belongs to a viewer account (read-scoped by design) or was revoked.
Fix: Check the API Keys page and lastUsedAt.
log_image warns "unrecognized image format"
Bytes are not PNG/JPEG/WEBP.
Fix: Use supported image formats. For numpy arrays, install Pillow (pip install Pillow).
log_image warns "need pillow"
Numpy arrays require Pillow for encoding.
Fix: pip install Pillow
next_trial keeps raising
The sweep was finished/cancelled (check the sweep page) or the worker's key lost write access.
Missing tail points
The process exited without finish(). Buffered points (up to 5s / 50 points) were lost with the daemon thread.
Fix: Always call cursus.finish() in a finally block.