{"record":{"id":"ac598a45047aa82a","repo":"BerriAI/litellm","slug":"unknown-mapper-name-name-r-known-known","errorCode":null,"errorMessage":"unknown mapper name {name!r}; known: {known}","messagePattern":"unknown mapper name (.+?); known: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/integrations/otel/mappers/__init__.py","lineNumber":47,"sourceCode":"_TOOL_DEFINITION_MAPPERS: Final[dict[str, Callable[[int], AttributeMapper]]] = {\n    \"genai\": GenAIMapper,\n    \"legacy\": LegacyMapper,\n    \"openinference\": OpenInferenceMapper,\n}\n_PLAIN_MAPPERS: Final[dict[str, Callable[[], AttributeMapper]]] = {\n    \"langfuse\": LangfuseMapper,\n    \"weave\": WeaveMapper,\n    \"langtrace\": LangtraceMapper,\n}\n\n\ndef resolve_mappers(names: Iterable[str]) -> list[AttributeMapper]:\n    \"\"\"Resolve mapper names to instances. Unknown names raise ``ValueError``.\"\"\"\n    ordered: Final = tuple(names)\n    for name in ordered:\n        if name not in _TOOL_DEFINITION_MAPPERS and name not in _PLAIN_MAPPERS:\n            known = sorted((*_TOOL_DEFINITION_MAPPERS, *_PLAIN_MAPPERS))\n            raise ValueError(f\"unknown mapper name {name!r}; known: {known}\")\n    # Distinct vocabularies each write the tool family under their own keys, so\n    # the ceiling is split by how many of them are configured. Repeating a name\n    # rewrites the same keys, so only distinct ones count.\n    budget: Final = tool_attr_budget(len({*ordered} & _TOOL_DEFINITION_MAPPERS.keys()))\n    return [\n        _TOOL_DEFINITION_MAPPERS[name](budget) if name in _TOOL_DEFINITION_MAPPERS else _PLAIN_MAPPERS[name]()\n        for name in ordered\n    ]\n\n\n__all__ = [\n    \"AttrValue\",\n    \"AttributeMap\",\n    \"AttributeMapper\",\n    \"GenAIMapper\",\n    \"LangfuseMapper\",\n    \"LangtraceMapper\",\n    \"LegacyMapper\",","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/integrations/otel/mappers/__init__.py#L29-L65","documentation":"The OTel v2 callback resolves its attribute vocabularies by name via resolve_mappers(). Valid names are genai, legacy, and openinference (tool-definition mappers) plus langfuse, weave, and langtrace (plain mappers); any other entry raises ValueError with the unknown name and the sorted list of known names. The config key feeding this is mapper_names in the OpenTelemetry v2 config (config.mapper_names), which layers semantic-convention vocabularies onto each span.","triggerScenarios":"Configuring the v2 OTel callback with a misspelled or unsupported vocabulary, e.g. mapper_names: [genai, openai] (openai is not a mapper — the Arize/Phoenix vocabulary is openinference), or pluralized/case-sensitive variants like Langfuse or weaves. Resolution happens when the logger builds, so it fails at startup or first use of the callback.","commonSituations":"Assuming the vendor name matches the mapper name (openai, arize, phoenix are all invalid; openinference covers Arize/Phoenix); case mismatch (Langfuse vs langfuse — lookup is exact); stale docs or examples from a version before new mappers were added (e.g. weave/langtrace missing in an older install, so a valid-in-docs name is unknown in the installed release).","solutions":["Use exactly one of the known names: genai, legacy, openinference, langfuse, weave, langtrace — all lowercase","Fix the common typo: openai -> openinference when you want Arize/Phoenix attribute keys","If a documented name is reported unknown, upgrade litellm — newer releases added mappers (weave, langtrace)","Rely on the error's sorted known-list rather than memory when editing the config"],"exampleFix":"# before\nmapper_names: [\"genai\", \"openai\"]\n# after\nmapper_names: [\"genai\", \"openinference\"]","handlingStrategy":"type-guard","validationCode":"KNOWN_MAPPERS = {'genai', 'legacy', 'openinference', 'langfuse', 'weave', 'langtrace'}\nnames = cfg['otel'].get('mapper_names', [])\nunknown = [n for n in names if n not in KNOWN_MAPPERS]\nif unknown:\n    raise SystemExit(f'unknown mapper_names {unknown}; known: {sorted(KNOWN_MAPPERS)}')","typeGuard":"def is_known_mapper(name: str) -> bool:\n    \"\"\"True when name is a resolvable OTel v2 attribute vocabulary.\"\"\"\n    return name in {'genai', 'legacy', 'openinference', 'langfuse', 'weave', 'langtrace'}","tryCatchPattern":"try:\n    from litellm.integrations.otel.mappers import resolve_mappers\n    mappers = resolve_mappers(names)\nexcept ValueError as e:\n    if 'unknown mapper name' in str(e):\n        raise ConfigError(f'fix mapper_names: {e}') from e\n    raise","preventionTips":["Use the error's printed known-list as the source of truth for the installed version","Remember vendor name != mapper name: Arize/Phoenix coverage comes from 'openinference', not 'arize'/'phoenix'/'openai'","Mapper names are lowercase and exact — 'Langfuse' fails","Re-run a resolve_mappers smoke test in CI whenever mapper_names or the litellm version changes"],"tags":["opentelemetry","otel","configuration","mapper-names","validation","v2"],"backgroundTag":"unknown-config-value","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}