What causes "Black Forest Labs generation timed out." in vercel/ai?

Increase `pollTimeoutMillis` in provider settings (e.g. bfl({ pollTimeoutMillis: 300000 })).

Black Forest Labs generation timed out.

Error message

Black Forest Labs generation timed out.

What it means

`pollForImageUrl` polls the BFL task endpoint at `pollIntervalMillis` intervals until `pollTimeoutMillis` elapses. If the task never reaches a terminal Ready/Error status within that window, the loop exits and this plain Error is thrown, meaning the generation is still pending but the SDK stopped waiting.

Source

Thrown at packages/black-forest-labs/src/black-forest-labs-image-model.ts:363

            imageUrl: value.result.sample,
            seed: value.result.seed ?? undefined,
            start_time: value.result.start_time ?? undefined,
            end_time: value.result.end_time ?? undefined,
            duration: value.result.duration ?? undefined,
          };
        }
        throw new Error(
          'Black Forest Labs poll response is Ready but missing result.sample',
        );
      }
      if (status === 'Error' || status === 'Failed') {
        throw new Error('Black Forest Labs generation failed.');
      }

      await delay(pollIntervalMillis);
    }

    throw new Error('Black Forest Labs generation timed out.');
  }
}

function convertSizeToAspectRatio(
  size: string,
): BlackForestLabsAspectRatio | undefined {
  const [wStr, hStr] = size.split('x');
  const width = Number(wStr);
  const height = Number(hStr);
  if (
    !Number.isFinite(width) ||
    !Number.isFinite(height) ||
    width <= 0 ||
    height <= 0
  ) {
    return undefined;
  }
  const g = gcd(width, height);

View on GitHub (pinned to 69428b1f8b)

Solutions

Increase `pollTimeoutMillis` in provider settings (e.g. bfl({ pollTimeoutMillis: 300000 })).
Reduce `pollIntervalMillis` slightly to poll more often, keeping within rate limits.
Retry the request; if it consistently times out, use a smaller image size or a faster FLUX model.
Check BFL service status for degradation causing unusually long generation times.

Example fix

// before
const bfl = createBlackForestLabs({ apiKey: process.env.BFL_API_KEY });

// after: allow up to 5 minutes of polling
const bfl = createBlackForestLabs({
  apiKey: process.env.BFL_API_KEY,
  pollIntervalMillis: 2000,
  pollTimeoutMillis: 300000,
});

Defensive patterns

Strategy: fallback

Validate before calling

if (typeof pollTimeoutMillis === 'number' && pollTimeoutMillis < 60000) {
  console.warn('pollTimeoutMillis below 60s may time out on large BFL generations');
}

Try / catch

try {
  return await generateImage({ model: bfl.image('flux-pro-1.1'), prompt });
} catch (e) {
  if ((e as Error).message === 'Black Forest Labs generation timed out.') {
    // fall back to smaller size or queue for async retry
    return generateImage({ model: bfl.image('flux-pro-1.1'), prompt, size: '512x512' });
  }
  throw e;
}

Prevention

Set generous pollTimeoutMillis (>= 5 minutes) for high-resolution generations.
Keep pollIntervalMillis around 1-2 seconds to balance latency and rate limits.
Prefer smaller sizes or faster FLUX variants in latency-sensitive paths.

When it happens

Trigger: Calling generateImage with a Black Forest Labs model while the task stays pending longer than the configured `pollTimeoutMillis` (default finite value) — e.g. very large images, slow BFL queue, or a too-short timeout setting.

Common situations: High BFL API load/long queues; users lowering pollTimeoutMillis for fast-fail CI; large size requests (e.g. high-resolution FLUX outputs) exceeding default timeout; long-running batch jobs hitting the wait limit.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/cd40f1ae8a0af795. Report an issue: GitHub.