microsoft/autogen · error · ReferenceNotFoundError

Reference `{ref_name}` not found in cache. Available: {list(

Error message

Reference `{ref_name}` not found in cache. Available: {list(self._model_cache.keys())}

What it means

Error "Reference `{ref_name}` not found in cache. Available: {list(self._model_cache.keys())}" thrown in microsoft/autogen.

Source

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

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."""
        import hashlib

        # Create a short hash of the full path to ensure uniqueness
        full_path = f"{parent_model_name}_{array_field_name}"
        hash_suffix = hashlib.md5(full_path.encode()).hexdigest()[:6]

        # Use field name as-is with hash suffix
        return f"{array_field_name}_{hash_suffix}"

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Resolve references in dependency order

Example fix

Register/convert the referenced model before referencing it

When it happens

Trigger: Thrown at python/packages/autogen-core/src/autogen_core/utils/_json_to_pydantic.py:122 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/2a03d5c627a49335. Report an issue: GitHub.