langchain-ai/langchain · error · ValueError

Must pass in a non-empty structured output schema. Received:

Error message

Must pass in a non-empty structured output schema. Received: {schema_}

What it means

Raised by the `StructuredPrompt` constructor when no output schema is supplied: the `schema_` positional/keyword argument is falsy and no `schema` key exists in `kwargs`. The schema defines the structure the piped model must produce via `with_structured_output`, so an empty/missing schema is a hard `ValueError`. The falsy check also rejects empty dicts/lists explicitly passed as schemas.

Source

Thrown at libs/core/langchain_core/prompts/structured.py:71

    ) -> None:
        """Create a structured prompt template.

        Args:
            messages: Sequence of messages.
            schema_: Schema for the structured prompt.
            structured_output_kwargs: Additional kwargs for structured output.
            template_format: Template format for the prompt.

        Raises:
            ValueError: If schema is not provided.
        """
        schema_ = schema_ or kwargs.pop("schema", None)
        if not schema_:
            err_msg = (
                "Must pass in a non-empty structured output schema. Received: "
                f"{schema_}"
            )
            raise ValueError(err_msg)
        # Avoid mutating a caller-provided dict when merging extra kwargs.
        structured_output_kwargs = dict(structured_output_kwargs or {})
        for k in set(kwargs).difference(get_pydantic_field_names(self.__class__)):
            structured_output_kwargs[k] = kwargs.pop(k)
        super().__init__(
            messages=messages,
            schema_=schema_,
            structured_output_kwargs=structured_output_kwargs,
            template_format=template_format,
            **kwargs,
        )

    @classmethod
    def get_lc_namespace(cls) -> list[str]:
        """Get the namespace of the LangChain object.

        For example, if the class is `langchain.llms.openai.OpenAI`, then the namespace
        is `["langchain", "llms", "openai"]`

View on GitHub (pinned to e32fa9a52e)

Solutions

Pass a real schema as the second argument: a Pydantic model class (e.g. `class Joke(BaseModel): setup: str; punchline: str`) or a JSON-schema dict
If generating schemas dynamically, guard that the result is non-empty before constructing the prompt
Check the spelling of the parameter if passing by keyword — use the schema positional argument to avoid `schema_`/`schema` confusion

Example fix

# before
prompt = StructuredPrompt.from_messages_and_schema(
    [("system", "You are a comedian")],
)  # ValueError: Must pass in a non-empty structured output schema

# after
from pydantic import BaseModel

class Joke(BaseModel):
    setup: str
    punchline: str

prompt = StructuredPrompt.from_messages_and_schema(
    [("system", "You are a comedian"), ("human", "tell a joke about {topic}")],
    Joke,
)

Defensive patterns

Strategy: type-guard

Validate before calling

def is_usable_schema(schema: object) -> bool:
    return schema is not None and schema != {} and schema != []

Type guard

from pydantic import BaseModel

def is_valid_schema(schema: object) -> bool:
    if isinstance(schema, type) and issubclass(schema, BaseModel):
        return len(schema.model_fields) > 0
    return isinstance(schema, dict) and len(schema) > 0

Try / catch

try:
    prompt = StructuredPrompt.from_messages_and_schema(messages, schema)
except ValueError as e:
    if "non-empty structured output schema" in str(e):
        raise ValueError("provide a Pydantic model or JSON-schema dict") from e
    raise

Prevention

Define one Pydantic model per structured task and keep it non-empty
Validate dynamically built schemas have at least one field before use
Pass the schema positionally to avoid schema/schema_ keyword confusion

When it happens

Trigger: `StructuredPrompt.from_messages_and_schema(messages)` with the schema argument omitted, `None`, or `{}`; or legacy call style `StructuredPrompt.from_messages_and_schema(messages, schema=None)`. Also triggers when a caller passes the schema under a misspelled keyword so `schema_` stays None.

Common situations: Copy-pasting `ChatPromptTemplate.from_messages` code and swapping only the class name, forgetting the required schema argument; building schemas dynamically and accidentally passing an empty Pydantic model or `{}` when a list of fields is empty; refactor renames (`schema` vs `schema_`) across versions.

Related errors

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/5d1abe7fe90e8915. Report an issue: GitHub.