vercel/ai · error · InvalidArgumentError

The separator " " must not be part of the alphabet " ".

Error message

The separator "${separator}" must not be part of the alphabet "${alphabet}".

What it means

createIdGenerator builds IDs as prefix + separator + random-part, and callers often check generated IDs with prefix matching (startsWith). If the separator is a character that also occurs in the random alphabet, prefix detection becomes ambiguous, so the library rejects such configurations at construction time with InvalidArgumentError. It is thrown eagerly when creating the generator (with a prefix), not when generating IDs.

Solutions

1. Pick a separator character that is not in the alphabet, e.g. the default '-' (or another symbol like '_' or ':' for custom alphabets that exclude it).
2. If you need a specific separator, exclude that character from your custom alphabet.
3. Do not pass an empty string as separator; omit the option to use the default '-' or choose a non-empty symbol.
4. Validate the configuration in tests/bootstrap so the InvalidArgumentError surfaces at deploy time, not at request time.

Example fix

// before: separator 'x' is inside the default alphabet
const gen = createIdGenerator({ prefix: 'msg', separator: 'x' });

// after: use a symbol outside the alphabet
const gen = createIdGenerator({ prefix: 'msg', separator: '-' });
// or with a numeric-only alphabet, a letter separator is fine
const gen2 = createIdGenerator({ alphabet: '0123456789', prefix: 'msg', separator: 'x' });

function assertValidSeparator(alphabet: string, separator: string): void {
  if (alphabet.includes(separator)) {
    throw new Error(`separator "${separator}" must not appear in alphabet "${alphabet}"`);
  }
}
assertValidSeparator('0123456789ABC...', '-');

try {
  const gen = createIdGenerator({ prefix: 'msg', separator });
} catch (error) {
  if (error instanceof InvalidArgumentError && error.argument === 'separator') {
    // fall back to the default '-' separator
  }
  throw error;
}

When it happens

Trigger: Calling createIdGenerator({ prefix: '...', separator: 'x' }) where separator is one of the characters contained in alphabet — e.g. the default alphabet contains all letters and digits, so any alphanumeric separator like 'a', '0', or 'Z' triggers it; only symbols outside the alphabet (like the default '-') are valid.

Common situations: Choosing a letter or digit separator assuming the alphabet is numeric-only; using an empty string separator ('' is contained in every string, so it always throws); copying a custom alphabet but keeping a separator drawn from it; wiring the generator in middleware at startup so the app crashes on boot.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

• callers for tool " " must be an array.
• Chunking must be "word", "line", a RegExp, an…
• Invalid argument for parameter output: Invalid output type.
• tool " " contains an invalid caller.
• unknown tool " ".

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

Appendix: source

Thrown at packages/provider-utils/src/generate-id.ts:39

  size?: number;
  alphabet?: string;
} = {}): IdGenerator => {
  const generator = () => {
    const alphabetLength = alphabet.length;
    const chars = new Array(size);
    for (let i = 0; i < size; i++) {
      chars[i] = alphabet[(Math.random() * alphabetLength) | 0];
    }
    return chars.join('');
  };

  if (prefix == null) {
    return generator;
  }

  // check that the prefix is not part of the alphabet (otherwise prefix checking can fail randomly)
  if (alphabet.includes(separator)) {
    throw new InvalidArgumentError({
      argument: 'separator',
      message: `The separator "${separator}" must not be part of the alphabet "${alphabet}".`,
    });
  }

  return () => `${prefix}${separator}${generator()}`;
};

/**
 * A function that generates an ID.
 */
export type IdGenerator = () => string;

/**
 * Generates a 16-character random string to use for IDs.
 * Not cryptographically secure.
 */
export const generateId = createIdGenerator();

View on GitHub (pinned to 69428b1f8b)