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

# Reference

> Process exit codes and generic worker limitations

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.

| Code                               | Cause                                                                         | Remediation                                                              |
| ---------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `CREDENTIALS_NOT_FOUND`            | `~/.blobhub-worker/credentials.yaml` is missing.                              | Run [`blobhub-worker login`](/worker/cli/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`](/worker/cli/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](/worker/configuration).                |
| `UNKNOWN_JOB_TYPE`                 | A section's `job_type` is not one of the supported values.                    | Use a supported value (see [Job Types](/worker/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](/worker/session-agent-harness/reference).

## Generic limitations

These trade-offs apply regardless of which [job type](/worker/job-types) 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

* [Configuration](/worker/configuration)
* [Reference](/worker/session-agent-harness/reference)