OpenAI Files API upload response has an invalid byte count

Error message

OpenAI Files API upload response has an invalid byte count

What it means

Thrown by parseOpenAIFileResponse when the bytes field is not a non-negative safe integer. The library requires an accurate byte count on every upload response because it feeds size accounting and handle metadata; a missing, fractional, negative, or oversized value is rejected.

Source

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

			pathname === "/v1"
		);
	} catch {
		return false;
	}
}

function parseOpenAIFileResponse(payload: unknown): OpenAIFileResponse {
	const file = payload as Partial<OpenAIFileResponse> | null;
	if (file === null || typeof file !== "object") {
		throw new Error("OpenAI Files API returned an invalid upload response");
	}

	const { id, bytes, status } = file;
	if (typeof id !== "string" || id.trim().length === 0) {
		throw new Error("OpenAI Files API upload response is missing a file id");
	}
	if (typeof bytes !== "number" || !Number.isSafeInteger(bytes) || bytes < 0) {
		throw new Error("OpenAI Files API upload response has an invalid byte count");
	}
	if (status !== "uploaded" && status !== "processed" && status !== "error") {
		throw new Error("OpenAI Files API upload response has an invalid status");
	}
	return { id, bytes, status };
}

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.
 */

View on GitHub (pinned to 9690622007)

Solutions

If using an OpenAI-compatible gateway, check whether it reports bytes; patch/upgrade the gateway or compute bytes client-side from the uploaded payload.
Inspect the raw response and coerce a numeric string before parsing if the gateway is known to stringify numbers.
Update test fixtures to use real integer byte counts from actual OpenAI responses.
Report/fix the gateway bug — the official OpenAI Files API always returns an integer bytes value.

Example fix

// before
typeGuardParse(body); // body.bytes = "1536"
// after: normalize gateway response
const fixed = { ...body, bytes: Number(body.bytes) };
const parsed = parseOpenAIFileResponse(fixed);

Defensive patterns

Strategy: validation

Validate before calling

const bytes = (body as { bytes?: unknown }).bytes;
if (typeof bytes === "string" && /^\d+$/.test(bytes)) body.bytes = Number(bytes);
if (typeof body.bytes !== "number" || !Number.isSafeInteger(body.bytes) || body.bytes < 0) {
  throw new Error(`gateway returned unusable bytes: ${String(bytes)}`);
}

Prevention

Normalize numeric strings from gateways before parsing
For gateways that omit bytes, compute the size client-side from the uploaded payload
Fix test fixtures to use integer byte counts
Report schema drift in OpenAI-compatible servers you depend on

When it happens

Trigger: Calling upload() when the OpenAI response's bytes field is absent, undefined, a string ("1234"), a float (1234.5), negative, or exceeds Number.MAX_SAFE_INTEGER — usually from a non-OpenAI-compatible gateway or hand-built mock.

Common situations: OpenAI-compatible servers (vLLM, LocalAI, proxies) that omit or stringify bytes; test fixtures with placeholder values; gateways returning bytes as null for unknown sizes.

Related errors

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