HeyPuter/puter · error · HttpError

unknown_error

unknown_error

Error message

Failed to extract image URL from OpenAI response

What it means

Thrown by OpenAiImageProvider.generate() (OpenAiImageProvider.ts:276) after a successful images.generate or images.edit call when result.data[0] has neither a `url` nor a `b64_json` field. Billing has already been recorded at this point. HTTP 400 unknown_error — the OpenAI response lacked the expected image payload.

Source

Thrown at src/backend/drivers/ai-image/providers/openai/OpenAiImageProvider.ts:276

        if (outputCostInCents > 0) {
            usageEntries.push({
                usageType: `${usageType}:output`,
                usageAmount: Math.max(usage.outputTokens, 1),
                costOverride: this.#toMicroCents(outputCostInCents),
            });
        }
        if (usageEntries.length) {
            this.#meteringService.batchIncrementUsages(actor, usageEntries);
        }

        const url =
            result.data?.[0]?.url ||
            (result.data?.[0]?.b64_json
                ? `data:image/png;base64,${result.data[0].b64_json}`
                : null);

        if (!url) {
            throw new HttpError(
                400,
                'Failed to extract image URL from OpenAI response',
                { legacyCode: 'unknown_error' },
            );
        }

        return url;
    }

    #extractUsage(result: ImagesResponse): OpenAIImageUsage {
        const usage = (result.usage ?? {}) as ImagesResponse.Usage &
            Record<string, unknown>;
        const inputTokens = this.#toSafeCount(usage.input_tokens);
        const outputTokens = this.#toSafeCount(usage.output_tokens);

        const inputDetails = (usage.input_tokens_details ??
            {}) as unknown as Record<string, unknown>;
        const inputTextTokens = this.#toSafeCount(inputDetails.text_tokens);

View on GitHub (pinned to 908ec23eda)

Solutions

  1. Rephrase the prompt to avoid policy-violating content.
  2. Inspect the full result.data[0] object in logs for filter/error fields.
  3. Verify the `openai` npm package version is current and compatible with the model.
  4. Retry once for transient cases.
Defensive patterns

Strategy: retry

Try / catch

try {
  return await provider.generate(params);
} catch (e) {
  if (e instanceof HttpError && e.message.includes('extract image URL from OpenAI')) {
    return await provider.generate(params); // single retry
  }
  throw e;
}

Prevention

When it happens

Trigger: OpenAI returned data with an error/filter reason but no image; content policy filtered the result; the response shape changed across SDK/API versions; an empty data array or data[0] without image fields; the model returned a text refusal in a non-standard field.

Common situations: Prompt violated OpenAI content policy producing a filtered/empty result; SDK version drift; model returning b64 under a different key; transient API anomaly.

Related errors

AI-assisted analysis of HeyPuter/puter@908ec23eda (2026-08-12). Data as JSON: /api/errors/104e7d0b1a8af45d. Report an issue: GitHub.