blob broker worker requires ${BLOB_BROKER_SOCKET_ENV} and ${

Error message

blob broker worker requires ${BLOB_BROKER_SOCKET_ENV} and ${BLOB_BROKER_CONFIG_ENV}

What it means

startBlobBrokerFromEnvironment() boots the blob broker daemon inside a worker, reading its socket path and JSON config from fixed environment variables (BLOB_BROKER_SOCKET_ENV / BLOB_BROKER_CONFIG_ENV). It throws when either variable is missing or empty — i.e. the function was invoked outside the broker worker harness that is supposed to set them.

Source

Thrown at packages/coding-agent/src/blob-broker/server.ts:152

					headers: { [RENDER_CALLBACK_TOKEN_HEADER]: token },
					signal: AbortSignal.timeout(CALLBACK_TIMEOUT_MS),
				});
				if (!response.ok) return null;
				return new Uint8Array(await response.arrayBuffer());
			});
			if (!publication) return json({ error: "unavailable" }, 503);
			return json({ publication } satisfies EnsureBlobResponse);
		}
		return json({ error: "not found" }, 404);
	};
}

/** Boot the blob daemon from worker environment variables and serve forever. */
export async function startBlobBrokerFromEnvironment(): Promise<void> {
	const socketPath = Bun.env[BLOB_BROKER_SOCKET_ENV];
	const configJson = Bun.env[BLOB_BROKER_CONFIG_ENV];
	if (!socketPath || !configJson) {
		throw new Error(`blob broker worker requires ${BLOB_BROKER_SOCKET_ENV} and ${BLOB_BROKER_CONFIG_ENV}`);
	}
	const config = JSON.parse(configJson) as BlobBrokerWorkerConfig;
	const backend = new LocalBlobBackend(config);
	// Bring the exposure up before advertising readiness so a ready daemon is a
	// serving daemon. Uploader configs have nothing to start.
	const baseUrl = isUploaderKind(config.kind) ? "" : await backend.ensureStarted();
	if (baseUrl === null) {
		throw new Error("blob broker exposure failed to start");
	}
	try {
		fs.rmSync(socketPath, { force: true });
	} catch {
		// A live daemon holding the socket loses the start race in the broker.
	}
	Bun.serve({ unix: socketPath, fetch: createControlHandler(backend, config, baseUrl) });
	// The daemon broker tears us down with a signal; flush the persisted
	// url index rather than losing the debounced write.
	process.on("SIGTERM", () => {

View on GitHub (pinned to 9690622007)

Solutions

Set both env vars before invoking: BLOB_BROKER_SOCKET_ENV=<socket path> and BLOB_BROKER_CONFIG_ENV=<JSON config>, e.g. via the same Worker spawn options the broker normally uses
Spawn the worker through the existing broker code path instead of invoking the entry function manually
If spawning manually, pass env: { ...process.env, [BLOB_BROKER_SOCKET_ENV]: sock, [BLOB_BROKER_CONFIG_ENV]: JSON.stringify(config) }
Verify the config JSON also parses — this guard runs before JSON.parse, so fix env first, then config contents

Example fix

// before: worker spawned without its env
new Worker(entry, { type: "module" });
// after
new Worker(entry, {
  type: "module",
  env: {
    ...process.env,
    [BLOB_BROKER_SOCKET_ENV]: socketPath,
    [BLOB_BROKER_CONFIG_ENV]: JSON.stringify(config),
  },
});

Defensive patterns

Strategy: validation

Validate before calling

// verify the harness env before booting
import { BLOB_BROKER_SOCKET_ENV, BLOB_BROKER_CONFIG_ENV } from "./env";
if (!Bun.env[BLOB_BROKER_SOCKET_ENV] || !Bun.env[BLOB_BROKER_CONFIG_ENV]) {
  throw new Error(`worker misconfigured: set ${BLOB_BROKER_SOCKET_ENV} and ${BLOB_BROKER_CONFIG_ENV}`);
}
JSON.parse(Bun.env[BLOB_BROKER_CONFIG_ENV]); // config must also be valid JSON

Try / catch

try {
  await startBlobBrokerFromEnvironment();
} catch (err) {
  if (String(err.message).includes("blob broker worker requires")) {
    logger.error("broker worker spawned without required env", { err });
  }
  throw err;
}

Prevention

Always spawn the worker through the existing broker spawn path, not by hand
Pass env: { ...process.env, ...brokerEnv } explicitly in Worker options
If env constant names change, update spawner and reader together in one commit
Smoke-test worker startup in CI with the real env wiring

When it happens

Trigger: Calling startBlobBrokerFromEnvironment() directly (or via runWorkerEntrypoint) without first setting both env vars; spawning the worker without passing env; a typo'd or stripped env when constructing the Worker.

Common situations: Manual testing of the worker entrypoint in a plain shell; spawning the worker with a custom env object that dropped the broker vars; refactors renaming the env constants so the spawner and the reader disagree.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/c62a42f4baba4955. Report an issue: GitHub.