An OpenAI API credential is required for file uploads

Error message

An OpenAI API credential is required for file uploads

What it means

Thrown by createOpenAIFileClient when the supplied credential is empty or whitespace-only. The factory only builds an OpenAI file client for official OpenAI Responses models, and since every Files API request requires a Bearer token, it fails fast at construction instead of producing 401s later on each upload.

Source

Thrown at packages/coding-agent/src/blob-broker/provider-files-openai.ts:73

function fileName(request: ProviderFileUploadRequest): string {
	const preferred = request.filename?.trim().replaceAll("\\", "/").split("/").pop();
	return preferred && preferred !== "." && preferred !== ".." ? preferred : "image";
}

/**
 * Create an OpenAI Files API client for an official OpenAI Responses model.
 *
 * Models using Codex, Azure, OpenRouter, or another OpenAI-compatible endpoint
 * are rejected locally by returning `null`; no request is attempted for them.
 */
export function createOpenAIFileClient(
	model: Model,
	credential: string,
	fetchImpl?: FetchImpl,
): ProviderFileClient | null {
	if (!isOfficialOpenAIResponsesModel(model)) return null;
	if (credential.trim().length === 0) throw new Error("An OpenAI API credential is required for file uploads");

	const request = fetchImpl ?? globalThis.fetch;
	const authorization = `Bearer ${credential}`;

	return {
		provider: "openai",
		async upload(uploadRequest: ProviderFileUploadRequest): Promise<ProviderFileHandle> {
			const form = new FormData();
			form.append("purpose", "vision");
			form.append(
				"file",
				new Blob([uploadRequest.bytes], { type: uploadRequest.mimeType }),
				fileName(uploadRequest),
			);

			let response: Response;
			try {
				response = await request(OPENAI_FILES_URL, {

View on GitHub (pinned to 9690622007)

Solutions

Set OPENAI_API_KEY (or the credential your wiring passes) to a valid non-empty API key and restart the process.
Check how empty values arise: a dotenv loader may override a real key with an empty entry later in the file — inspect the final value at runtime.
Add a startup check that fails fast when OpenAI models are configured but the key is blank.
In CI, ensure the secret is actually injected into the environment (secrets are not inherited by default in some CI systems).
If OpenAI file upload is not intended, verify the configured model is not an official OpenAI Responses model, since that triggers credential requirement.

Example fix

// before
const key = process.env.OPENAI_API_KEY ?? ""; // empty when unset
const client = createOpenAIFileClient(model, key); // throws
// after
const key = process.env.OPENAI_API_KEY;
if (!key?.trim()) throw new Error("Set OPENAI_API_KEY to use OpenAI file uploads");
const client = createOpenAIFileClient(model, key);

Defensive patterns

Strategy: validation

Validate before calling

const key = process.env.OPENAI_API_KEY;
if (typeof key !== "string" || key.trim().length === 0) {
  throw new Error("OPENAI_API_KEY is not set; cannot create OpenAI file client");
}

Try / catch

try {
  const client = createOpenAIFileClient(model, credential);
} catch (err) {
  if (String(err?.message).includes("credential is required")) {
    throw new Error("Set OPENAI_API_KEY (non-empty) to enable OpenAI file uploads");
  }
  throw err;
}

Prevention

Check for the credential at process startup, before any OpenAI model is used
Watch for dotenv entries that overwrite a valid key with an empty value
Verify CI actually injects the secret into the job environment
Guard client construction behind an explicit 'file uploads enabled' config flag

When it happens

Trigger: Calling createOpenAIFileClient (or the higher-level client()) with credential = "" or " " while the model is an official OpenAI Responses model — e.g. an unset OPENAI_API_KEY env var read as an empty string, or a config loader that defaults missing keys to "".

Common situations: OPENAI_API_KEY not set in the environment or .env file not loaded; config file with apiKey: "" placeholder; CI environment missing the secret; key rotated/removed but stale empty config remains; passing the wrong variable (e.g. an OAuth token variable that is empty).

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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