EasyAI
Request access Check your PC
Worker troubleshooting

Docs · Worker

Worker troubleshooting

Diagnose enrollment, heartbeat, capacity, and pipeline errors on a contributed worker.

On this page

Most worker problems show up as a failed enrollment, a stale heartbeat, or a request that never finds an eligible machine. Start with the app’s Status screen, then check the error code below.

Enrollment and authentication

Symptom Check
401 UNAUTHORIZED The session is expired or the worker was revoked. Enroll again with a fresh one-time token. User API keys do not authenticate worker routes.
410 PROTOCOL_INCOMPATIBLE The worker build is older than the control plane accepts. Update to a build from your invite.
Enrollment token rejected The token is single-use and may already have been consumed. Request a replacement through the invite channel.

Heartbeat and capacity

The worker sends a heartbeat every 10 seconds. The control plane keeps a heartbeat for 30 seconds, and the scheduler’s freshness window is 15 seconds. A worker with an older heartbeat is not eligible for new work.

If requests fail with 503 NO_CAPACITY, check each of these:

  • The worker is running and the Status screen says IDLE, not PAUSED or ERROR.
  • Contribution is enabled and the current time is inside the active-hours window.
  • The worker advertises the model the request needs. For the command-line worker, WORKER_MODELS must list it; an empty list means never scheduled.
  • Free or declared VRAM meets the plan requirement after the 15% safety margin.
  • The heartbeat is fresh. A paused, sleeping, or disconnected PC is not eligible.

Zero active workers means the network is degraded. Requests fail rather than pretending the model is served.

Pipeline worker errors

Pipeline-parallel work uses a front worker running llama-server and RPC workers running ggml-rpc-server.

  • 409 BUILD_SKEW: pin the same LLAMACPP_BUILD on the front and every RPC box. Current llama.cpp builds name the RPC binary ggml-rpc-server, so GGML_RPC_SERVER_BIN must point at that executable.
  • RPC_ADVERTISE_ADDR must be reachable from the front boxes, not from the control plane. Set it to the same host:port that RPC_LISTEN_PORT binds.
  • Weights live on the front box only, at MODEL_DIR/<ggufSha256>.gguf. A missing file or hash mismatch refuses the assignment before a process starts. RPC workers need no model file.
  • If the CUDA build cannot find its runtime, place cublas64_12.dll, cublasLt64_12.dll, and cudart64_12.dll next to llama-server.exe.
  • 409 ASSIGNMENT_NOT_READY is transient: the prompt hold may not have been written yet or the assignment state changed. Retry the poll.
  • 413 PAYLOAD_TOO_LARGE or 409 INVALID_CHUNKS means a token submission was too large or out of order. Update the worker and retry the job.

Desktop app issues

  • SmartScreen on install: the current installer is not code-signed. Verify the file came from the project, then choose More info → Run anyway.
  • Canned output only: the Canned runner is a fixture. Install Ollama, run ollama pull lfm3, and select the Ollama runner for real inference.
  • Worker idle with no jobs: a fresh network with no requests is expected. A single worker can serve a single-stage request; a missing model, stale heartbeat, or exhausted VRAM budget keeps it ineligible.
  • Diagnostics: export the redacted { profile, logTail, policy } bundle from the app. It strips enrollment tokens, bearer credentials, the device private key, and PEM material. Raw sidecar logs are under %APPDATA%\EasyAI\logs.

Pause and revoke

Pause works locally and does not need the control plane. Revoke requires the control plane: the app asks the server to remove the worker before it deletes local device credentials, and it fails closed if that call cannot complete.

If the control plane is unreachable, pause the worker now and retry revoke when it is reachable. See Worker limits.

Docs menu