BerriAI/litellm · error · ValueError

otel.attributes: unknown attribute name(s)

Error message

otel.attributes: unknown attribute name(s) {unknown}. Valid names: {sorted(VALID_METRIC_ATTRIBUTE_NAMES)}

What it means

The otel.attributes filter is allowlist-based: every name in include_list/exclude_list must be one of the recognized metric attributes. The valid set is gen_ai.operation.name, gen_ai.provider.name, gen_ai.system, gen_ai.request.model, gen_ai.framework, hidden_params, and metadata.<key> for each supported metadata key (user_api_key_hash, user_api_key_alias, user_api_key_team_id, user_api_key_org_id, user_api_key_user_id, user_api_key_team_alias, user_api_key_user_email, spend_logs_metadata, requester_ip_address, requester_metadata, user_api_key_end_user_id, prompt_management_metadata, applied_guardrails, mcp_tool_call_metadata, vector_store_request_metadata). Unknown names raise ValueError listing both the offenders and the sorted valid set.

Solutions

  1. Read the error: it prints the exact unknown names and the full sorted valid list for your installed version
  2. Fix typos/rename to a valid name — most intents map to gen_ai.request.model, gen_ai.system, gen_ai.provider.name, etc.
  3. For metadata-type attributes, use the exact metadata.<key> spelling from the valid list (e.g. metadata.user_api_key_team_id)
  4. If a name you expect is missing from the valid list, upgrade litellm — the allowlist may have gained entries in a newer release

Example fix

# before
attributes:
  include_list: [gen_ai.request_model, gen_ai.system]
# after
attributes:
  include_list: [gen_ai.request.model, gen_ai.system]
Defensive patterns

Strategy: validation

Validate before calling

METADATA_KEYS = {'user_api_key_hash','user_api_key_alias','user_api_key_team_id','user_api_key_org_id','user_api_key_user_id','user_api_key_team_alias','user_api_key_user_email','spend_logs_metadata','requester_ip_address','requester_metadata','user_api_key_end_user_id','prompt_management_metadata','applied_guardrails','mcp_tool_call_metadata','vector_store_request_metadata'}
BASE = {'gen_ai.operation.name','gen_ai.provider.name','gen_ai.system','gen_ai.request.model','gen_ai.framework','hidden_params'}
VALID = BASE | {f'metadata.{k}' for k in METADATA_KEYS}

attrs = config['otel'].get('attributes') or {}
requested = (attrs.get('include_list') or []) + (attrs.get('exclude_list') or [])
unknown = sorted(set(requested) - VALID)
if unknown:
    raise SystemExit(f'unknown otel.attributes names {unknown}; valid: {sorted(VALID)}')

Type guard

def known_metric_attributes(names: list[str]) -> list[str]:
    """Return the subset of names that are valid metric attribute filters."""
    return [n for n in names if n in VALID]  # VALID built as above

Try / catch

try:
    otel_cb = OpenTelemetry(attributes=attrs)
except ValueError as e:
    if 'unknown attribute name' in str(e):
        # the message prints valid names for the INSTALLED version; reconcile config to it
        raise ConfigError(f'fix otel.attributes names: {e}') from e
    raise

Prevention

When it happens

Trigger: Typing an attribute name wrong (gen_ai.request.model vs gen_ai.request_model, or gen_ai.response.model which is not in the metric set), inventing plausible names (gen_ai.token.type aside, e.g. gen_ai.usage.tokens), or using metadata.X where X is not one of the supported metadata keys. Validated eagerly for explicit config, or on first metric record for proxy callback_settings.

Common situations: Copying span attribute names (a much larger vocabulary) into the metric filter config; version skew where an older litellm emitted names no longer in the valid set (or vice versa: docs newer than the installed version); renaming drift between gen_ai semconv versions (e.g. gen_ai.system.identity vs gen_ai.system).

Related errors

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

Appendix: source

Thrown at litellm/integrations/opentelemetry.py:187


def _resolve_metric_attribute_filter(
    attributes: OTELMetricAttributeFilter | None,
) -> tuple[frozenset[str] | None, frozenset[str] | None]:
    if attributes is None:
        return None, None
    include: Final = attributes.include_list or None
    exclude: Final = attributes.exclude_list or None
    if include and exclude:
        raise ValueError("otel.attributes: include_list and exclude_list are mutually exclusive")
    requested: Final = include or exclude or []
    if TOKEN_TYPE_ATTRIBUTE in requested:
        raise ValueError(
            f"otel.attributes: {TOKEN_TYPE_ATTRIBUTE} is a structural token-usage discriminator and cannot be filtered"
        )
    unknown: Final = sorted(name for name in requested if name not in VALID_METRIC_ATTRIBUTE_NAMES)
    if unknown:
        raise ValueError(
            f"otel.attributes: unknown attribute name(s) {unknown}. Valid names: {sorted(VALID_METRIC_ATTRIBUTE_NAMES)}"
        )
    return (
        frozenset(include) if include else None,
        frozenset(exclude) if exclude else None,
    )


def _normalize_team_metadata_keys(value: Any) -> list[str]:
    """Coerce a team-metadata allowlist from a list or comma-separated string.

    config.yaml passes a YAML list; an env var passes a comma-separated string.
    Both collapse to a list of stripped, non-empty keys.
    """
    if value is None:
        return []
    if isinstance(value, str):
        return [item.strip() for item in value.split(",") if item.strip()]

View on GitHub (pinned to 77b7c6c40c)