What causes "top must be a positive integer" in microsoft/autogen?

microsoft/autogen · error · ValueError

top must be a positive integer

Error message

top must be a positive integer

What it means

The pydantic field validator for top rejects non-positive values: top must be a positive integer when provided (None is allowed and means the service default). top maps to the $top search parameter controlling how many results are returned.

Source

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

            raise ValueError("endpoint must be a valid URL starting with http:// or https://")
        return v

    @field_validator("query_type")
    def normalize_query_type(cls, v: QueryTypeLiteral) -> QueryTypeLiteral:
        """Normalize query type to standard values."""
        if not v:
            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")

View on GitHub (pinned to 027ecf0a37)

Solutions

Pass top>=1, e.g. top=5.
Use top=None (or omit it) for the service default number of results.
Clamp dynamic values: top=max(1, computed_top).

Example fix

# before
tool = AzureAISearchTool(name='s', endpoint=ep, index_name='idx', credential=cred, top=max(0, user_limit - page))
# after
tool = AzureAISearchTool(name='s', endpoint=ep, index_name='idx', credential=cred, top=max(1, user_limit - page))

Defensive patterns

Strategy: validation

Validate before calling

def top_is_valid(top) -> bool:
    return top is None or (isinstance(top, int) and not isinstance(top, bool) and top >= 1)

Type guard

def is_positive_top(top) -> bool:
    return top is None or (isinstance(top, int) and top > 0)

Prevention

Clamp computed values: top = max(1, computed) or pass None for the service default.
Remember 0 is not 'unlimited' — omit top or use None for the default result count.
Validate top in config schemas with minimum: 1.

When it happens

Trigger: Passing top=0 or a negative number to any Azure AI Search tool factory or to AzureAISearchConfig directly; computing top dynamically (e.g. top=limit - requested) where the arithmetic can reach 0.

Common situations: top derived from user input or pagination math that underflows to 0; copying a config where top was decremented; treating 0 as 'no limit' (the API treats None/omission as the default, not 0).

Related errors

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