microsoft/autogen · error · ReferenceNotFoundError

Reference `{ref}` not found in `$defs`. Available keys: {lis

Error message

Reference `{ref}` not found in `$defs`. Available keys: {list(definitions.keys())}

What it means

Error "Reference `{ref}` not found in `$defs`. Available keys: {list(definitions.keys())}" thrown in microsoft/autogen.

Source

Thrown at python/packages/autogen-core/src/autogen_core/utils/_json_to_pydantic.py:114

    """Construct a Pydantic Field with proper typing."""
    field_kwargs: Dict[str, Any] = {}
    if title is not None:
        field_kwargs["title"] = title
    if description is not None:
        field_kwargs["description"] = description
    return Field(default, **field_kwargs)


class _JSONSchemaToPydantic:
    def __init__(self) -> None:
        self._model_cache: Dict[str, Optional[Union[Type[BaseModel], ForwardRef]]] = {}

    def _resolve_ref(self, ref: str, schema: Dict[str, Any]) -> Dict[str, Any]:
        ref_key = ref.split("/")[-1]
        definitions = cast(dict[str, dict[str, Any]], schema.get("$defs", {}))

        if ref_key not in definitions:
            raise ReferenceNotFoundError(
                f"Reference `{ref}` not found in `$defs`. Available keys: {list(definitions.keys())}"
            )

        return definitions[ref_key]

    def get_ref(self, ref_name: str) -> Any:
        if ref_name not in self._model_cache:
            raise ReferenceNotFoundError(
                f"Reference `{ref_name}` not found in cache. Available: {list(self._model_cache.keys())}"
            )

        if self._model_cache[ref_name] is None:
            return ForwardRef(ref_name)

        return self._model_cache[ref_name]

    def _get_item_model_name(self, array_field_name: str, parent_model_name: str) -> str:
        """Generate hash-based model names for array items to keep names short and unique."""

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Add the referenced definition or fix the ref

Example fix

Ensure every $ref has a matching key in $defs

When it happens

Trigger: Thrown at python/packages/autogen-core/src/autogen_core/utils/_json_to_pydantic.py:114 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/cc4957c483ec3c01. Report an issue: GitHub.