{"record":{"id":"0a603988e3814ef3","repo":"BerriAI/litellm","slug":"invalid-key-alias-format-must-be-2-255-characters","errorCode":null,"errorMessage":"Invalid key_alias format. Must be 2-255 characters, start/end with alphanumeric, and only contain a-zA-Z0-9_-/.@.","messagePattern":"Invalid key_alias format\\. Must be 2-255 characters, start/end with alphanumeric, and only contain a-zA-Z0-9_-/\\.@\\.","errorType":"http","errorClass":"ProxyException","httpStatus":400,"severity":"warning","filePath":"litellm/proxy/management_endpoints/key_management_endpoints.py","lineNumber":6639,"sourceCode":"    \"\"\"\n    if key_alias is None:\n        return\n\n    try:\n        raise_if_unsafe_secret_name(key_alias)\n    except ValueError:\n        raise ProxyException(\n            message=\"Invalid key_alias\",\n            type=ProxyErrorTypes.bad_request_error,\n            param=\"key_alias\",\n            code=400,\n        )\n\n    if not litellm.enable_key_alias_format_validation:\n        return\n\n    if not _KEY_ALIAS_PATTERN.match(key_alias):\n        raise ProxyException(\n            message=\"Invalid key_alias format. Must be 2-255 characters, start/end with alphanumeric, and only contain a-zA-Z0-9_-/.@.\",\n            type=ProxyErrorTypes.bad_request_error,\n            param=\"key_alias\",\n            code=400,\n        )\n\n\nasync def _enforce_unique_key_alias(\n    key_alias: str | None,\n    prisma_client: PrismaClient | None,\n    existing_key_token: str | None = None,\n) -> None:\n    \"\"\"\n    Helper to enforce unique key aliases across all keys.\n\n    Args:\n        key_alias (Optional[str]): The key alias to check\n        prisma_client (Any): Prisma client instance","sourceCodeStart":6621,"sourceCodeEnd":6657,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/management_endpoints/key_management_endpoints.py#L6621-L6657","documentation":"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.","triggerScenarios":"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/'.","commonSituations":"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.","solutions":["Shape aliases as slug-style strings: start and end with a letter/digit, keep to a-zA-Z0-9_-/.@ inside, length 2–255","Trim and replace disallowed characters before sending: re.sub(r'[^a-zA-Z0-9_\\-/\\.@]', '-', alias).strip('-')","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","Add the regex to your client-side tests so generated aliases can never violate it"],"exampleFix":"# before\nawait client.post('/key/generate', json={'key_alias': '-prod key!'})\n# 400: Invalid key_alias format. Must be 2-255 characters, start/end with alphanumeric...\n# after\nawait client.post('/key/generate', json={'key_alias': 'prod-key-1'})","handlingStrategy":"validation","validationCode":"import re\n\n_KEY_ALIAS_RE = re.compile(r'^[a-zA-Z0-9][a-zA-Z0-9_\\-/\\.@]{0,253}[a-zA-Z0-9]$')\n\ndef conform_alias(alias: str) -> str:\n    a = re.sub(r'[^a-zA-Z0-9_\\-/\\.@]', '-', alias.strip()).lstrip('-_/').rstrip('-_/')\n    return (a + '-x')[:255] if len(a) < 2 else a[:255]","typeGuard":"def is_valid_alias(alias: object) -> bool:\n    return isinstance(alias, str) and bool(_KEY_ALIAS_RE.match(alias))","tryCatchPattern":"if not is_valid_alias(alias):\n    alias = conform_alias(alias)\ntry:\n    await client.post('/key/generate', json={'key_alias': alias})\n    ...","preventionTips":["Reuse the exact regex ^[a-zA-Z0-9][a-zA-Z0-9_\\-/\\.@]{0,253}[a-zA-Z0-9]$ in client tests","Cap generated aliases well under 255 chars","Only enable litellm.enable_key_alias_format_validation after existing aliases have been audited against the pattern"],"tags":["key-alias","validation","regex","litellm-proxy","format"],"backgroundTag":"invalid-identifier-format","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-21T13:17:26.733Z"}