HeyPuter/puter · error · HttpError

unknown_error

unknown_error

Error message

Cloudflare image generation failed with status ${response.status}

What it means

After POSTing to Cloudflare's endpoint, if the HTTP response is not ok (non-2xx), the provider tries to extract a message from the JSON payload; if extraction fails it throws HTTP 400 unknown_error with 'Cloudflare image generation failed with status <status>'. The raw status comes from Cloudflare's API response.

Source

Thrown at src/backend/drivers/ai-image/providers/cloudflare/CloudflareImageProvider.ts:410

        ).toLowerCase();
        if (contentType.startsWith('image/')) {
            const imageBuffer = Buffer.from(await response.arrayBuffer());
            return `data:${contentType};base64,${imageBuffer.toString('base64')}`;
        }

        const text = await response.text();
        let payload: unknown;
        try {
            payload = text ? JSON.parse(text) : {};
        } catch {
            payload = { raw: text };
        }

        if (!response.ok) {
            const message =
                this.#extractErrorMessage(payload) ||
                `Cloudflare image generation failed with status ${response.status}`;
            throw new HttpError(400, message, { legacyCode: 'unknown_error' });
        }

        if (typeof payload === 'object' && payload !== null) {
            const envelope = payload as Record<string, unknown>;
            if (envelope.success === false) {
                const message =
                    this.#extractErrorMessage(payload) ||
                    'Cloudflare image generation failed';
                throw new HttpError(400, message, {
                    legacyCode: 'unknown_error',
                });
            }
        }

        const imageString = this.#extractImageString(payload);
        if (!imageString) {
            throw new HttpError(
                400,

View on GitHub (pinned to 908ec23eda)

Solutions

  1. Check the Cloudflare API token/account config is valid and has the right permissions.
  2. Verify the model id and request shape are accepted by Cloudflare (consult Cloudflare Workers AI docs).
  3. If status is 429, back off and retry with exponential delay.
  4. Inspect Cloudflare status page for incidents if status is 5xx.

Example fix

// before — bad/expired token in config causes non-ok response
// after — verify the token and model id, then retry on 429
// config: ensure cloudflare.api_token is valid and account has Workers AI access
Defensive patterns

Strategy: retry

Validate before calling

// No pure pre-check for upstream non-ok; validate config instead.
if (!cloudflareConfig.api_token) throw new Error('Cloudflare API token not configured');

Try / catch

try {
  await provider.generate({ prompt });
} catch (e) {
  const status = /status (\d+)/.exec(e?.message ?? '')?.[1];
  if (e?.code === 'unknown_error' && status === '429') {
    await sleep(backoffMs); await provider.generate({ prompt }); // retry on rate limit
  } else throw e;
}

Prevention

When it happens

Trigger: Cloudflare returns a non-2xx for the generation request — auth error (bad API token → 401), rate limit (429), bad request (400), or upstream error (5xx) — and either no error message or a non-JSON body.

Common situations: Wrong/expired Cloudflare API token (config), exhausted Cloudflare quota, invalid model id sent to Cloudflare, Cloudflare API incident, malformed request payload.

Related errors

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