vercel/ai · error · UnsupportedFunctionalityError

Anthropic Message Batches do not support per-request betas

Error message

Anthropic Message Batches do not support per-request betas (request "${request.id}"). Set providerOptions.anthropic.anthropicBeta on startTextBatch instead.

What it means

Anthropic Message Batches apply beta headers at the batch level, so per-request `providerOptions.anthropic.anthropicBeta` values are unsupported. experimental_doStartBatch checks each request's betas and throws an UnsupportedFunctionalityError naming the request and directing you to set the beta on startTextBatch instead.

Solutions

Remove anthropicBeta from individual request providerOptions.
Pass `providerOptions.anthropic.anthropicBeta` at the startTextBatch level instead.
Verify after refactor that the batch call no longer includes per-request betas.

Example fix

// before
await model.experimental_doStartBatch({
  requests: [{ id: '1', options: { providerOptions: { anthropic: { anthropicBeta: ['context-1h'] } } } }],
});
// after
await model.experimental_doStartBatch({
  providerOptions: { anthropic: { anthropicBeta: ['context-1h'] } },
  requests: [{ id: '1', options: {} }],
});

Defensive patterns

Strategy: validation

Validate before calling

const perRequestBetas = request.options?.providerOptions?.anthropic?.anthropicBeta;
if (perRequestBetas) throw new Error('Move anthropicBeta to startTextBatch-level providerOptions');

Type guard

function hasPerRequestBetas(req: { options?: { providerOptions?: { anthropic?: { anthropicBeta?: unknown } } } }): boolean {
  const b = req.options?.providerOptions?.anthropic?.anthropicBeta;
  return Array.isArray(b) ? b.length > 0 : b != null;
}

Try / catch

try {
  await model.experimental_doStartBatch(args);
} catch (e) {
  if (e instanceof Error && e.message.includes('do not support per-request betas')) {
    // hoist anthropicBeta to startTextBatch-level providerOptions
  }
  throw e;
}

Prevention

Never attach anthropicBeta to per-request providerOptions in batch workflows.
Set betas once at the batch level.
Strip request-level providerOptions when converting streaming code to batch code.

When it happens

Trigger: Calling `experimental_doStartBatch` (via batch start) with requests that carry `providerOptions: { anthropic: { anthropicBeta: ... } }` — any non-empty per-request betas list triggers the error.

Common situations: Reusing a standard streaming requestOptions object for batch requests; copying code that sets anthropicBeta per request for prompt caching or context management into batch workflows.

Related errors

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

Appendix: source

Thrown at packages/anthropic/src/anthropic-messages-batch.ts:215

        ? []
        : [
            {
              warning: {
                type: 'unsupported',
                feature: 'webhookUrl',
                details:
                  'The Anthropic Message Batches API does not support completion webhooks.',
              },
            },
          ];

    for (const request of requests) {
      const requestBetas = await getAnthropicBatchProviderBetas({
        provider: this.config.provider,
        providerOptions: request.options.providerOptions,
      });
      if (requestBetas.length > 0) {
        throw new UnsupportedFunctionalityError({
          functionality: 'per-request providerOptions.anthropic.anthropicBeta',
          message:
            `Anthropic Message Batches do not support per-request betas ` +
            `(request "${request.id}"). Set providerOptions.anthropic.anthropicBeta ` +
            `on startTextBatch instead.`,
        });
      }

      const prepared = await this.getArgs({
        ...request.options,
        stream: false,
        userSuppliedBetas: new Set(explicitBatchBetas),
      });
      if (prepared.usesJsonResponseTool) {
        throw new UnsupportedFunctionalityError({
          functionality: 'batch responseFormat JSON-tool fallback',
          message:
            `Anthropic Message Batches cannot decode the JSON-tool structured-output fallback ` +

View on GitHub (pinned to 69428b1f8b)