{"record":{"id":"c9635e06e9f73f23","repo":"deepset-ai/haystack","slug":"unsupported-document-comparison-field-self-docu","errorCode":null,"errorMessage":"Unsupported document_comparison_field: '{self.document_comparison_field}'. Use 'content', 'id', or 'meta.<key>'.","messagePattern":"Unsupported document_comparison_field: '(.+?)'\\. Use 'content', 'id', or 'meta\\.<key>'\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"haystack/components/evaluators/document_map.py","lineNumber":80,"sourceCode":"        Extract the comparison value from a document based on the configured field.\n        \"\"\"\n        if self.document_comparison_field == \"content\":\n            return doc.content\n        if self.document_comparison_field == \"id\":\n            return doc.id\n        if self.document_comparison_field.startswith(\"meta.\"):\n            parts = self.document_comparison_field[5:].split(\".\")\n            value = doc.meta\n            for part in parts:\n                if not isinstance(value, dict) or part not in value:\n                    return None\n                value = value[part]\n            return value\n        msg = (\n            f\"Unsupported document_comparison_field: '{self.document_comparison_field}'. \"\n            \"Use 'content', 'id', or 'meta.<key>'.\"\n        )\n        raise ValueError(msg)\n\n    def to_dict(self) -> dict[str, Any]:\n        \"\"\"\n        Serializes the component to a dictionary.\n\n        :returns:\n            Dictionary with serialized data.\n        \"\"\"\n        return default_to_dict(self, document_comparison_field=self.document_comparison_field)\n\n    # Refer to https://www.pinecone.io/learn/offline-evaluation/ for the algorithm.\n    @component.output_types(score=float, individual_scores=list[float])\n    def run(\n        self, ground_truth_documents: list[list[Document]], retrieved_documents: list[list[Document]]\n    ) -> dict[str, Any]:\n        \"\"\"\n        Run the DocumentMAPEvaluator on the given inputs.\n","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/evaluators/document_map.py#L62-L98","documentation":"DocumentMAPEvaluator._get_comparison_value resolves each Document's comparison value from the configured document_comparison_field. It raises ValueError when that field is none of 'content', 'id', or a string starting with 'meta.', i.e. the constructor was given an unsupported field specifier.","triggerScenarios":"Constructing `DocumentMAPEvaluator(document_comparison_field=\"text\")` or any value not 'content'/'id'/'meta.<key>'; a deserialized YAML with a typo like 'Content' or missing 'meta.' prefix; the error surfaces at run() time when documents are compared.","commonSituations":"Typos in YAML pipeline configs (case sensitivity, missing 'meta.' prefix); using a bare meta key like 'file_id' instead of 'meta.file_id'; migrating configs from older evaluator versions with different option names.","solutions":["Set document_comparison_field to exactly 'content', 'id', or 'meta.<key>'","For a meta field, prefix the key: `document_comparison_field=\"meta.file_id\"`","Validate the config value at construction time before running pipelines"],"exampleFix":"// before\nevaluator = DocumentMAPEvaluator(document_comparison_field=\"file_id\")\n// after\nevaluator = DocumentMAPEvaluator(document_comparison_field=\"meta.file_id\")","handlingStrategy":"validation","validationCode":"allowed = lambda v: v in (\"content\", \"id\") or v.startswith(\"meta.\")\nif not allowed(document_comparison_field):\n    raise ValueError(f\"Unsupported field: {document_comparison_field}\")","typeGuard":"def is_valid_comparison_field(field: object) -> bool:\n    return isinstance(field, str) and (field in (\"content\", \"id\") or field.startswith(\"meta.\"))","tryCatchPattern":"try:\n    result = evaluator.run(ground_truth_documents=gt, retrieved_documents=ret)\nexcept ValueError as e:\n    if \"Unsupported document_comparison_field\" in str(e):\n        evaluator.document_comparison_field = \"content\"\n        result = evaluator.run(ground_truth_documents=gt, retrieved_documents=ret)\n    else:\n        raise","preventionTips":["Validate document_comparison_field at construction time","Remember meta keys need the 'meta.' prefix (e.g. 'meta.file_id')","Watch case sensitivity in YAML configs","Round-trip to_dict/from_dict in tests to catch config typos"],"tags":["python","value-error","evaluators","configuration"],"backgroundTag":"invalid-config-option","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}