microsoft/autogen · error · ValueError

semantic_config_name must be provided when query_type is 'se

Error message

semantic_config_name must be provided when query_type is 'semantic'

What it means

AzureAISearchConfig's model_validator (mode='after') enforces interdependent rules once all fields are parsed. The first rule: query_type='semantic' requires semantic_config_name. This is the config-level backstop behind the factory-level checks (errors 932/934) and also fires when configs are deserialized from component configs/JSON rather than built via factories.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/tools/azure/_config.py:173

            return "simple"

        if isinstance(v, str) and v.lower() == "fulltext":
            return "full"

        return v

    @field_validator("top")
    def validate_top(cls, v: Optional[int]) -> Optional[int]:
        """Ensure top is a positive integer if provided."""
        if v is not None and v <= 0:
            raise ValueError("top must be a positive integer")
        return v

    @model_validator(mode="after")
    def validate_interdependent_fields(self) -> "AzureAISearchConfig":
        """Validate interdependent fields after all fields have been parsed."""
        if self.query_type == "semantic" and not self.semantic_config_name:
            raise ValueError("semantic_config_name must be provided when query_type is 'semantic'")

        if self.query_type == "vector" and not self.vector_fields:
            raise ValueError("vector_fields must be provided for vector search")

        if (
            self.embedding_provider
            and self.embedding_provider.lower() == "azure_openai"
            and self.embedding_model
            and not self.openai_endpoint
        ):
            raise ValueError("openai_endpoint must be provided for azure_openai embedding provider")

        return self

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Add semantic_config_name matching a semantic configuration defined on the index.
2. Change query_type to 'simple'/'full' if semantic ranking is not needed.
3. When editing serialized component configs, re-validate by constructing AzureAISearchConfig(**dict) in a test before loading it in the agent.

Example fix

# before
AzureAISearchConfig(name='s', endpoint=ep, index_name='idx', credential=cred, query_type='semantic')
# after
AzureAISearchConfig(name='s', endpoint=ep, index_name='idx', credential=cred, query_type='semantic', semantic_config_name='my-semantic-config')

def config_interdependent_rules_ok(cfg_dict: dict) -> bool:
    if cfg_dict.get('query_type') == 'semantic' and not cfg_dict.get('semantic_config_name'):
        return False
    if cfg_dict.get('query_type') == 'vector' and not cfg_dict.get('vector_fields'):
        return False
    return True

def semantic_pair_valid(query_type, semantic_config_name) -> bool:
    return query_type != 'semantic' or bool(semantic_config_name)

try:
    cfg = AzureAISearchConfig(**config_dict)
except ValueError as e:  # pydantic ValidationError
    if 'semantic_config_name' in str(e):
        config_dict.setdefault('semantic_config_name', 'default')
        cfg = AzureAISearchConfig(**config_dict)
    else:
        raise

When it happens

Trigger: Constructing or deserializing AzureAISearchConfig(query_type='semantic') without semantic_config_name — including loading a saved component config where the field was dropped, or programmatically mutating a config dict.

Common situations: Round-tripping tool configs through the autogen component config system with an older config that predates semantic support; hand-written YAML/JSON component definitions missing the field; switching query_type in serialized config without updating companions.

Related errors

• Invalid configuration: {str(e)}
• semantic_config_name is required when query_type is 'semanti
• endpoint must be a valid URL starting with http:// or https:
• top must be a positive integer
• vector_fields must be provided for vector search

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