{"record":{"id":"3da26769c3c5e5a3","repo":"run-llama/llama_index","slug":"key-should-not-be-none","errorCode":null,"errorMessage":"Key should not be None","messagePattern":"Key should not be None","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/prompts/guidance_utils.py","lineNumber":94,"sourceCode":"        return json_schema_to_guidance_output_template(\n            root[\"$defs\"][model], key, indent, root\n        )\n\n    if schema[\"type\"] == \"object\":\n        out += \"  \" * indent + \"{\\n\"\n        for k, v in schema[\"properties\"].items():\n            out += (\n                \"  \" * (indent + 1)\n                + f'\"{k}\"'\n                + \": \"\n                + json_schema_to_guidance_output_template(v, k, indent + 1, root)\n                + \",\\n\"\n            )\n        out += \"  \" * indent + \"}\"\n        return out\n    elif schema[\"type\"] == \"array\":\n        if key is None:\n            raise ValueError(\"Key should not be None\")\n        if \"max_items\" in schema:\n            extra_args = f\" max_iterations={schema['max_items']}\"\n        else:\n            extra_args = \"\"\n        return (\n            \"[{{#geneach '\"\n            + key\n            + \"' stop=']'\"\n            + extra_args\n            + \"}}{{#unless @first}}, {{/unless}}\"\n            + json_schema_to_guidance_output_template(schema[\"items\"], \"this\", 0, root)\n            + \"{{/geneach}}]\"\n        )\n    elif schema[\"type\"] == \"string\":\n        if key is None:\n            raise ValueError(\"key should not be None\")\n        return \"\\\"{{gen '\" + key + \"' stop='\\\"'}}\\\"\"\n    elif schema[\"type\"] in [\"integer\", \"number\"]:","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/prompts/guidance_utils.py#L76-L112","documentation":"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.","triggerScenarios":"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[...]]).","commonSituations":"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.","solutions":["Wrap the array in an object: define output_cls with a field like items: List[Item] instead of a bare list/RootModel.","If calling the util directly, pass a non-None key for the array (e.g. 'items').","Upgrade llama-index-core — newer guidance_utils handles root arrays more gracefully."],"exampleFix":"# before\nclass Album(BaseModel):\n    __root__: List[Track]  # root-level array -> schema type 'array', key None\n# after\nclass Album(BaseModel):\n    tracks: List[Track]  # array nested under a named key","handlingStrategy":"validation","validationCode":"schema = output_cls.model_json_schema()\nif schema.get(\"type\") == \"array\":\n    raise ValueError(\"wrap list output in an object field, e.g. items: List[T]\")","typeGuard":"def schema_root_is_array(output_cls) -> bool:\n    return output_cls.model_json_schema().get(\"type\") == \"array\"","tryCatchPattern":null,"preventionTips":["Never use RootModel[List[...]] or bare lists as guidance program output classes.","Name every collection with an explicit field so the schema arrays always have keys."],"tags":["guidance","json-schema","arrays","pydantic"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}