run-llama/llama_index · error · ValueError

Key should not be None

Error message

Key should not be None

What it means

While emitting a guidance geneach block for a JSON schema array, the converter needs a key name to bind the generated list to. Arrays lack their own name, so the parent object must pass the property name as key; if key is None (e.g. the array is the top-level schema), generation cannot proceed and this ValueError is raised.

Source

Thrown at llama-index-core/llama_index/core/prompts/guidance_utils.py:94

        return json_schema_to_guidance_output_template(
            root["$defs"][model], key, indent, root
        )

    if schema["type"] == "object":
        out += "  " * indent + "{\n"
        for k, v in schema["properties"].items():
            out += (
                "  " * (indent + 1)
                + f'"{k}"'
                + ": "
                + json_schema_to_guidance_output_template(v, k, indent + 1, root)
                + ",\n"
            )
        out += "  " * indent + "}"
        return out
    elif schema["type"] == "array":
        if key is None:
            raise ValueError("Key should not be None")
        if "max_items" in schema:
            extra_args = f" max_iterations={schema['max_items']}"
        else:
            extra_args = ""
        return (
            "[{{#geneach '"
            + key
            + "' stop=']'"
            + extra_args
            + "}}{{#unless @first}}, {{/unless}}"
            + json_schema_to_guidance_output_template(schema["items"], "this", 0, root)
            + "{{/geneach}}]"
        )
    elif schema["type"] == "string":
        if key is None:
            raise ValueError("key should not be None")
        return "\"{{gen '" + key + "' stop='\"'}}\""
    elif schema["type"] in ["integer", "number"]:

View on GitHub (pinned to afd0fef371)

Solutions

1. Wrap the array in an object: define output_cls with a field like items: List[Item] instead of a bare list/RootModel.
2. If calling the util directly, pass a non-None key for the array (e.g. 'items').
3. Upgrade llama-index-core — newer guidance_utils handles root arrays more gracefully.

Example fix

# before
class Album(BaseModel):
    __root__: List[Track]  # root-level array -> schema type 'array', key None
# after
class Album(BaseModel):
    tracks: List[Track]  # array nested under a named key

schema = output_cls.model_json_schema()
if schema.get("type") == "array":
    raise ValueError("wrap list output in an object field, e.g. items: List[T]")

def schema_root_is_array(output_cls) -> bool:
    return output_cls.model_json_schema().get("type") == "array"

When it happens

Trigger: Calling json_schema_to_guidance_output_template with a top-level schema of type 'array' (key defaults to None); reached via GuidancePydanticProgram whose output_cls serializes to a root-level JSON array (e.g. RootModel[List[...]]).

Common situations: Using a Pydantic model whose JSON schema root is an array (lists of items as the final output); older guidance_utils versions that did not handle root-level arrays; hand-built schemas without a wrapping object.

Related errors

• Must specify root schema for nested object
• key should not be None
• Unknown schema type {schema_type}
• Failed to parse pydantic object from guidance program. Proba
• There are {len(self.selections)} selections, please use .ind

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/3da26769c3c5e5a3. Report an issue: GitHub.