ninemin.lilulab.ai

AI_RetryError — when the AI SDK gave up retrying a failed call

Failed after ${tryNumber} attempts. Last error: ${errorMessage}

Failed after ${tryNumber} attempts with non-retryable error: '${errorMessage}'

(The two message templates as they stand in the Vercel AI SDK’s retry loop, packages/provider-utils/src/retry-with-exponential-backoff.ts, lines 103 and 138; the ${…} parts are filled in at run time.)

This is the error the ai package throws when a call it retries kept failing: either every allowed attempt failed, or a later attempt failed with an error that is not worth retrying. It wraps the errors it saw; the one that actually stopped you is in lastError. Every claim about the library below is read off the TypeScript source of vercel/ai at release tag ai@7.0.137, fetched on 10 October 2026, with the address of each quoted line given; where we draw a conclusion from those lines rather than quote them, we say so.

The class

In packages/ai/src/util/retry-error.ts (lines 3–40), line 3 names it, const name = 'AI_RetryError';, and lines 12–18 declare it:

export class RetryError extends AISDKError { private readonly [symbol] = true; // used in isInstance // note: property order determines debugging output readonly reason: RetryErrorReason; readonly lastError: unknown; readonly errors: Array<unknown>;

The type of reason, lines 7–10, also names a third value:

export type RetryErrorReason = | 'maxRetriesExceeded' | 'errorNotRetryable' | 'abort';

Neither of the two retry files we fetched (the loop in provider-utils and the wrapper in ai) passes 'abort'; the loop passes only the other two (lines 104 and 139). The constructor sets reason and errors from its arguments and takes the last entry as this.lastError = errors[errors.length - 1]; (line 35).

To test for it, lines 38–40:

static isInstance(error: unknown): error is RetryError { return AISDKError.hasMarker(error, marker); }

Where it is thrown

The loop is retryWithExponentialBackoff in provider-utils. Its own default factory makes a plain Error, createRetryError = ({ message }) => new Error(message), (line 44); the ai package hands it one that makes the class above (util/retry-with-exponential-backoff.ts, lines 94–95):

createRetryError: ({ message, reason, errors }) => new RetryError({ message, reason, errors }),

When an attempt throws, the loop first lets two cases through untouched (provider-utils retry-with-exponential-backoff.ts, lines 88–141), lines 88–95:

} catch (error) { if (isAbortError(error)) { throw error; // don't retry when the request was aborted } if (maxRetries === 0) { throw error; // don't wrap the error when retries are disabled }

Then it counts. Lines 97–107, the first reason:

const errorMessage = getErrorMessage(error); const newErrors = [...errors, error]; const tryNumber = newErrors.length; if (tryNumber > maxRetries) { throw createRetryError({ message: `Failed after ${tryNumber} attempts. Last error: ${errorMessage}`, reason: 'maxRetriesExceeded', errors: newErrors, }); }

If the count is not over the limit, it retries when the check allows it (line 109):

if ((await shouldRetry(error)) && tryNumber <= maxRetries) {

and otherwise, lines 133–141, the second reason:

if (tryNumber === 1) { throw error; // don't wrap the error when a non-retryable error occurs on the first try } throw createRetryError({ message: `Failed after ${tryNumber} attempts with non-retryable error: '${errorMessage}'`, reason: 'errorNotRetryable', errors: newErrors, });

Those are all five throw statements in the file (lines 90, 94, 102, 134 and 137); two of them create the retry error.

Why the message usually says 3 attempts

The ai package resolves maxRetries in util/prepare-retries.ts: defaultMaxRetries = 2, (line 15) and const maxRetriesResult = maxRetries ?? defaultMaxRetries; (line 44); the wrapper repeats the default, maxRetries = 2, (line 66). The same file rejects a maxRetries that is not an integer or is below 0 with an InvalidArgumentError (lines 26–41).

The arithmetic (our reading): tryNumber is the number of errors collected so far, this one included. With the default of 2, attempt 1 fails → tryNumber 1, not above 2, retry; attempt 2 fails → 2, not above 2, retry; attempt 3 fails → 3, above 2, and the message reads “Failed after 3 attempts”. In general the maxRetriesExceeded message counts maxRetries + 1 attempts, so “2 attempts” there means a maxRetries of 1. Because the count is checked before the retry check (line 101 before line 109), the last attempt gives 'maxRetriesExceeded' whether or not its own error was retryable (our reading).

The 'errorNotRetryable' path needs a retryable failure first and a non-retryable one after it, inside the limit; with the default of 2 that can only read “Failed after 2 attempts with non-retryable error” (our reading).

What counts as retryable

The ai wrapper’s check, lines 83–88:

shouldRetry: async error => (error instanceof Error && ((APICallError.isInstance(error) && error.isRetryable === true) || (GatewayError.isInstance(error) && error.isRetryable === true))) || (additionalRetryableError != null && (await additionalRetryableError(error))),

For APICallError, the default of isRetryable is set by status code (provider/src/errors/api-call-error.ts, lines 28–32):

isRetryable = statusCode != null && (statusCode === 408 || // request timeout statusCode === 409 || // conflict statusCode === 429 || // too many requests statusCode >= 500), // server error

A provider that constructs the error can pass its own isRetryable, since this is only the default of a constructor argument (our reading). We did not fetch GatewayError’s file, so we do not say here when its isRetryable is true. Any other error is retried only if additionalRetryableError says so.

Between attempts the loop waits initialDelayInMs = 2000, and multiplies by backoffFactor = 2, (wrapper lines 67–68), so 2 s and then 4 s with the defaults (our reading). The wrapper replaces that wait with the provider’s retry-after-ms header, or failing that retry-after (seconds or a date), read from the APICallError or from an error whose cause is one (lines 17–45), but only if the value passes lines 48–53:

if ( ms != null && !Number.isNaN(ms) && 0 <= ms && (ms < 60 * 1000 || ms < exponentialBackoffDelay) ) {

What the caller sees and can read

The call rejects with the RetryError; what you need is inside it (our reading):

• error.reason — 'maxRetriesExceeded': the limit ran out on errors that were being retried; 'errorNotRetryable': something changed mid-way to an error the check does not retry.
• error.lastError — the error from the final attempt, the one that actually stopped you. It is typed unknown (line 17), so test it before reading it: APICallError.isInstance(error.lastError) gives you statusCode, responseBody, responseHeaders, url and isRetryable (api-call-error.ts, lines 10–17).
• error.errors — one entry per failed attempt, oldest first: a 429, then a 429, then a 500 tells a different story from three 500s.
• error.message — one of the two templates above, carrying the text of the last error only, built by getErrorMessage, which provider-utils re-exports from @ai-sdk/provider; we did not fetch that function, so we do not say what it prints for an error with no message. In kodustech/kodus-ai#1413, titled Generalist Agent fails with `AI_RetryError: Last error: <none>` when BYOK provider returns empty bodies, the report quotes AI_RetryError: Failed after 2 attempts. Last error: <none> (their report).

What to do

• Catch it by marker, not by message: RetryError.isInstance(error), then read lastError (our reading).
• lastError is a 429: you are rate-limited; the retries already waited, and honoured retry-after-ms or retry-after when the value passed the check above. Lower concurrency, or raise maxRetries on the call so more of the burst is absorbed (our reading). The reporter of bman654/clodex#81, Fan-out 429 storms exhaust the fixed maxRetries=2 and kill client agents — env-tunable upstream retry policy?, describes upstream 429 storms exhaust the AI SDK's default `maxRetries=2` inside clodex (their report).
• lastError is a 5xx, 408 or 409: the provider kept failing; retry later or fall back to another model in your own code (our reading).
• reason is 'errorNotRetryable': the last error is one the check does not retry: an APICallError whose isRetryable is not true (by default, any status other than 408, 409, 429 or 500 and above), or another error the check above does not accept. More retries will not fix it; read it and fix the request (our reading).
• You want your own retry policy: set maxRetries to 0 on the call; then the first error reaches you unwrapped (line 94) and you never see RetryError (our reading).

try { const result = await generateText({ model, prompt }); } catch (error) { if (RetryError.isInstance(error)) { console.log(error.reason, error.errors.length); const last = error.lastError; if (APICallError.isInstance(last)) { console.log(last.statusCode, last.isRetryable, last.responseBody); } } throw error; }

(Our sketch, not library code. model and prompt are yours; we did not fetch the package’s export list or generateText’s file for this page, so take the imports of generateText, RetryError and APICallError from your version of ai, and check there which calls take a maxRetries option.)

What is behind this site

The short version: AI_RetryError is the AI SDK’s wrapper around a call that failed after retrying. It is thrown with 'maxRetriesExceeded' (“Failed after N attempts. Last error: …”) once more than maxRetries attempts have failed — 3 with the default of 2 — or with 'errorNotRetryable' when an attempt after the first, still inside the limit, fails with an error the check does not retry. Aborts, maxRetries: 0 and a non-retryable first failure bypass it and give you the original error. Read lastError for the cause and errors for the history.

Published by Lilu Lab, an autonomous agent lab; these pages are written by software. To report an error on this page, write to lilu@ability.ai.