> ## 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` | No API key from `--api-key`, `BLOBHUB_API_KEY`, or a stored profile — or the credentials file is present but malformed. | Run [`blobhub-worker login`](/worker/cli/login), or supply a key directly. | | `PROFILE_NOT_FOUND` | `--profile` or `BLOBHUB_PROFILE` names a profile that is not stored, or is not a valid profile name. | `blobhub-worker profile ls` to see what is stored. | | `INPUT_REQUIRED` | Raised only by `login`: a supplied literal or stdin value — `--api-key`/`--api-key-stdin`, or the API-URL/realtime-URL equivalents — came back empty after trimming; or nothing supplied the API key and prompting was unavailable (`--no-input`, no TTY, or stdin already claimed by another `-stdin` flag) or left blank when prompted. An unset or blank `-env` variable is `ENV_VAR_NOT_SET` below, never this — that check runs first. | Supply the key with `--api-key-stdin` (preferred), `--api-key`, or `--api-key-env VAR`, and make sure the source isn't blank. | | `ENV_VAR_NOT_SET` | Raised only by `login`: the environment variable named by `--api-key-env`, `--api-url-env`, or `--realtime-url-env` is unset or empty. | Export the variable with a real value, or point the flag at one that already is. | | `INSECURE_CREDENTIALS_PERMISSIONS` | `~/.blobhub/credentials.yaml` is readable by group or other. | `chmod 600 ~/.blobhub/credentials.yaml`. It is refused, never repaired. | | `IDENTITY_NOT_FOUND` | The profile's `identity.yaml` is present but unreadable. **Absence is no longer an error** — it is recorded on first start. | Delete the corrupt file and start again. | | `USER_IDENTITY_MISMATCH` | The server's `user_id` differs from the one recorded for this profile. | 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 **this profile's** lock. Different profiles do not collide; the message names the one that does. | Stop that process. A stale lock is reclaimed automatically — whether it names a dead pid, or a pid that is alive but positively not a worker. | | `MIGRATION_CONFLICT` | A pre-profiles install was migrating, but `~/.blobhub/credentials.yaml` already holds a different `default` profile. | Rename or move the existing `default` aside, then start again. | | `INVALID_CONFIG` | `config.yaml` is missing, unreadable, or not valid YAML — or a section's `session_prefix`, or the top-level `policy` block, fails validation. | 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 `(org_id, blob_id, revision_id, session_id, session_prefix)` 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. `DUPLICATE_SECTION_TARGET` has a second, **section-level** realization too: when a section's `session_id` is a spelling (uuid or alias) that resolves, after attach, to a session another section is already serving under a different spelling — something this static check cannot see — that one section refuses while the rest of the worker keeps running. See [Session Agent Harness → Reference](/worker/session-agent-harness/reference). Section, thread, and transient codes are scoped to a job type. For `session_agent_harness`, see [Reference](/worker/session-agent-harness/reference). ## Instance command codes These come from `blobhub-worker instance show`/`instance stop`, not from `start`'s preflight — they are raised while inspecting or stopping an already-running worker, not while one is coming up. | Code | Raised by | Meaning | | ------------------------- | -------------- | ----------------------------------------------------------------------- | | `INSTANCE_NOT_FOUND` | `show`, `stop` | Selector matched no tree and no lock. | | `INSTANCE_AMBIGUOUS` | `show`, `stop` | Selector matched more than one; the message lists them. | | `INSTANCE_NOT_RUNNING` | `stop` | Target has no live worker to signal (`stopped`, or an unreadable lock). | | `INSTANCE_PID_NOT_WORKER` | `stop` | The lock's pid is alive but is positively not a worker. | | `INSTANCE_STOP_TIMEOUT` | `stop` | Still alive after the timeout (and after `SIGKILL`, under `--force`). | | `INSTANCE_SIGNAL_FAILED` | `stop` | The signal itself failed — permissions, typically. | Full behavior: [`blobhub-worker instance`](/worker/cli/instance). ## 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 the profile's `config.yaml` does **not** affect a running worker. Restart the worker (`blobhub-worker start`) to pick up changes. ### Single-process per profile Each worker runs in a single Python process and does not distribute work across machines or scale beyond `concurrency.max_agents` (in-process). The lock is held **per [profile](/worker/auth)**, not per machine, so one machine may run several workers side by side — `--profile prod` and `--profile staging` at once, each with its own configuration, cursors and lock. What is still refused is a second worker on the *same* profile. ## See also * [Configuration](/worker/configuration) * [`blobhub-worker instance`](/worker/cli/instance) * [Reference](/worker/session-agent-harness/reference)