ScrapeGraphAI/Scrapegraph-ai · error · ValueError

Invalid pydantic schema: missing 'properties' key

Error message

Invalid pydantic schema: missing 'properties' key

What it means

Raised by transform_schema when the provided pydantic schema dict does not contain a top-level 'properties' key, meaning it is not a valid JSON-schema-style object schema. The function only knows how to transform object schemas with properties.

Source

Thrown at scrapegraphai/utils/schema_trasform.py:52

                    else:
                        result[key] = ["unknown"]  # fallback for malformed array
                else:
                    result[key] = {
                        "type": value["type"],
                        "description": value.get("description", ""),
                    }
            elif "$ref" in value:
                ref_key = value["$ref"].split("/")[-1]
                if "$defs" in pydantic_schema and ref_key in pydantic_schema["$defs"]:
                    result[key] = process_properties(
                        pydantic_schema["$defs"][ref_key].get("properties", {})
                    )
                else:
                    result[key] = {"type": "object", "description": "Missing reference"}  # fallback
        return result

    if "properties" not in pydantic_schema:
        raise ValueError("Invalid pydantic schema: missing 'properties' key")
    return process_properties(pydantic_schema["properties"])

View on GitHub (pinned to 532dfffbf6)

Solutions

1. Ensure the schema is a pydantic model's JSON schema with at least one field: class Out(BaseModel): x: str -> Out.model_json_schema() has 'properties'
2. Wrap scalar outputs in a model with a named field
3. If using RootModel, replace it with a normal model containing fields
4. Log/inspect the schema dict before calling transform_schema

Example fix

# before
class Out(RootModel[str]): ...  # no 'properties'
transform_schema(Out.model_json_schema())
# after
class Out(BaseModel):
    answer: str
transform_schema(Out.model_json_schema())

schema = Out.model_json_schema()
assert "properties" in schema and schema["properties"], "schema must be an object model with fields"

def is_transformable_schema(schema: dict) -> bool:
    return isinstance(schema, dict) and isinstance(schema.get("properties"), dict) and len(schema["properties"]) > 0

try:
    transformed = transform_schema(schema)
except ValueError as e:
    raise ValueError(f"output schema invalid: {e}") from e

When it happens

Trigger: Calling transform_schema (used by graph execute paths that build structured output schemas) with a schema like {"type": "string"}, {"title": "X"}, or a raw $def-only dict lacking "properties".

Common situations: Passing a scalar/array output schema instead of an object with fields; passing model_json_schema() of a RootModel or a schema already transformed/trimmed; nesting errors where a subschema is passed instead of the top-level one.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• pydantic.v1 and langchain_core.pydantic_v1 are not supported
• The schema is not a pydantic subclass. With this LLM model y
• LLM configuration must include an 'api_key'.
• langchain_google_genai is not installed. Please install it u
• The browserbase module is not installed. Please install it u

AI-assisted analysis of ScrapeGraphAI/Scrapegraph-ai@532dfffbf6 (2026-08-28). Data as JSON: /api/errors/ddf59dcdac3b9c8e. Report an issue: GitHub.