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, 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.
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 (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.

Section, thread, and transient codes are scoped to a job type. For session_agent_harness, see 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.

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 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, 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
• blobhub-worker instance
• Reference