Skip to main content
This page is the user-facing reference for the worker process itself: the exit codes it raises during preflight, before any section is contacted, and the generic limitations that apply no matter which job type a section runs. Section, thread, and transient codes are scoped to a job type and documented with it.

​
Process exit codes

The worker refuses to run when any of these are detected at start. The failure exits the process with the code; nothing on the server is touched.
CodeCauseRemediation
CREDENTIALS_NOT_FOUND~/.blobhub-worker/credentials.yaml is missing.Run blobhub-worker login.
INSECURE_CREDENTIALS_PERMISSIONScredentials.yaml is world-readable.chmod 600 ~/.blobhub-worker/credentials.yaml.
IDENTITY_NOT_FOUND~/.blobhub-worker/identity.yaml is missing.Run blobhub-worker login.
USER_IDENTITY_MISMATCHThe server’s user_id differs from the recorded one.Confirm intent with login, or restore the prior identity.yaml.
AUTH_INVALIDGET /v1/users/me returned 401/403.Re-run login with a valid API key.
WORKER_ALREADY_RUNNINGAnother worker holds the instance lock (instance.yaml).Stop the other process. A stale dead-PID file is replaced automatically.
INVALID_CONFIGconfig.yaml is missing, unreadable, or not valid YAML.Fix the YAML; see Configuration.
UNKNOWN_JOB_TYPEA section’s job_type is not one of the supported values.Use a supported value (see Job Types).
MISSING_SESSION_KEYSA section is missing one of org_id, blob_id, revision_id, session_id.Complete the section’s session block.
DUPLICATE_SECTION_TARGETTwo sections target the same session tuple.Remove one of the duplicates.
MISSING_SESSION_KEYS and DUPLICATE_SECTION_TARGET are raised by the session_agent_harness section validator, which the loader runs at preflight; they still exit the process before any section is contacted. Section, thread, and transient codes are scoped to a job type. For session_agent_harness, see Reference.

​
Generic limitations

These trade-offs apply regardless of which job type a section runs. Job-type-specific limitations are documented with the job type.

​
No hot configuration reload

Editing ~/.blobhub-worker/config.yaml does not affect a running worker. Restart the worker (blobhub-worker start) to pick up changes.

​
Single-process, single-machine

The worker runs in a single Python process on a single machine. It does not distribute work across machines or scale beyond concurrency.max_agents (in-process).

​
See also