vercel/ai · error · InvalidArgumentError

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

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.

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)

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.

Related errors

• Invalid argument for parameter output: Invalid output type.
• Chunking must be "word", "line", a RegExp, an Intl.Segmenter
• unknown tool "${toolName}".
• callers for tool "${toolName}" must be an array.
• tool "${toolName}" contains an invalid caller.

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