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.Documentation Index
Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
Use this file to discover all available pages before exploring further.
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.| Code | Cause | Remediation |
|---|---|---|
CREDENTIALS_NOT_FOUND | ~/.blobhub-worker/credentials.yaml is missing. | Run blobhub-worker login. |
INSECURE_CREDENTIALS_PERMISSIONS | credentials.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_MISMATCH | The server’s user_id differs from the recorded one. | Confirm intent with login, or restore the prior identity.yaml. |
AUTH_INVALID | GET /v1/users/me returned 401/403. | Re-run login with a valid API key. |
WORKER_ALREADY_RUNNING | Another worker holds the instance lock (instance.yaml). | Stop the other process. A stale dead-PID file is replaced automatically. |
INVALID_CONFIG | config.yaml is missing, unreadable, or not valid YAML. | Fix the YAML; see Configuration. |
UNKNOWN_JOB_TYPE | A section’s job_type is not one of the supported values. | Use a supported value (see Job Types). |
MISSING_SESSION_KEYS | A section is missing one of org_id, blob_id, revision_id, session_id. | Complete the section’s session block. |
DUPLICATE_SECTION_TARGET | Two 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 beyondconcurrency.max_agents (in-process).