BerriAI/litellm · warning · ProxyException

Invalid key_alias format. Must be 2-255 characters, start/en

Error message

Invalid key_alias format. Must be 2-255 characters, start/end with alphanumeric, and only contain a-zA-Z0-9_-/.@.

What it means

Format validation for key_alias, enforced only when litellm.enable_key_alias_format_validation is on (otherwise this branch returns early). The regex is ^[a-zA-Z0-9][a-zA-Z0-9_\-/\.@]{0,253}[a-zA-Z0-9]$: 2–255 characters, must start and end with an alphanumeric, and may contain only a-zA-Z0-9, '_', '-', '/', '.', '@' in the middle. Failures get a 400 ProxyException whose detail spells out these rules.

Source

Thrown at litellm/proxy/management_endpoints/key_management_endpoints.py:6639

    """
    if key_alias is None:
        return

    try:
        raise_if_unsafe_secret_name(key_alias)
    except ValueError:
        raise ProxyException(
            message="Invalid key_alias",
            type=ProxyErrorTypes.bad_request_error,
            param="key_alias",
            code=400,
        )

    if not litellm.enable_key_alias_format_validation:
        return

    if not _KEY_ALIAS_PATTERN.match(key_alias):
        raise ProxyException(
            message="Invalid key_alias format. Must be 2-255 characters, start/end with alphanumeric, and only contain a-zA-Z0-9_-/.@.",
            type=ProxyErrorTypes.bad_request_error,
            param="key_alias",
            code=400,
        )


async def _enforce_unique_key_alias(
    key_alias: str | None,
    prisma_client: PrismaClient | None,
    existing_key_token: str | None = None,
) -> None:
    """
    Helper to enforce unique key aliases across all keys.

    Args:
        key_alias (Optional[str]): The key alias to check
        prisma_client (Any): Prisma client instance

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Shape aliases as slug-style strings: start and end with a letter/digit, keep to a-zA-Z0-9_-/.@ inside, length 2–255
2. Trim and replace disallowed characters before sending: re.sub(r'[^a-zA-Z0-9_\-/\.@]', '-', alias).strip('-')
3. If you cannot change producers yet, you may disable the check by leaving litellm.enable_key_alias_format_validation off — but fixing the data is the durable fix
4. Add the regex to your client-side tests so generated aliases can never violate it

Example fix

# before
await client.post('/key/generate', json={'key_alias': '-prod key!'})
# 400: Invalid key_alias format. Must be 2-255 characters, start/end with alphanumeric...
# after
await client.post('/key/generate', json={'key_alias': 'prod-key-1'})

import re

_KEY_ALIAS_RE = re.compile(r'^[a-zA-Z0-9][a-zA-Z0-9_\-/\.@]{0,253}[a-zA-Z0-9]$')

def conform_alias(alias: str) -> str:
    a = re.sub(r'[^a-zA-Z0-9_\-/\.@]', '-', alias.strip()).lstrip('-_/').rstrip('-_/')
    return (a + '-x')[:255] if len(a) < 2 else a[:255]

def is_valid_alias(alias: object) -> bool:
    return isinstance(alias, str) and bool(_KEY_ALIAS_RE.match(alias))

if not is_valid_alias(alias):
    alias = conform_alias(alias)
try:
    await client.post('/key/generate', json={'key_alias': alias})
    ...

When it happens

Trigger: Aliases like '-lead' or 'lead-' (non-alphanumeric edges), 'a' (1 char), a 300-char auto-generated name, 'my alias' (space), 'prod#1' ('#'), or a trailing slash 'team-a/'.

Common situations: Auto-derived aliases from emails ('user@acme.com' is fine but '+user@acme.com' is not), team names with spaces, or alias generators prepending '-' for 'disabled' markers.

Related errors

• Invalid budget_duration '{budget_duration}'. Use a format li
• Invalid key format.
• Invalid key_alias
• Unsupported image format: {image_format}. Supported formats:
• mcp_tools_config must be a list of dictionaries

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/0a603988e3814ef3. Report an issue: GitHub.