{"record":{"id":"cf2d6ce6b44b834f","repo":"doctrine/orm","slug":"index-by-is-not-a-valid-tag","errorCode":null,"errorMessage":"<index-by /> is not a valid tag","messagePattern":"<index-by /> is not a valid tag","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Mapping/Driver/XmlDriver.php","lineNumber":419,"sourceCode":"                }\n\n                if (isset($oneToManyElement['orphan-removal'])) {\n                    $mapping['orphanRemoval'] = $this->evaluateBoolean($oneToManyElement['orphan-removal']);\n                }\n\n                if (isset($oneToManyElement->{'order-by'})) {\n                    $orderBy = [];\n                    foreach ($oneToManyElement->{'order-by'}->{'order-by-field'} ?? [] as $orderByField) {\n                        $orderBy[(string) $orderByField['name']] = (string) ($orderByField['direction'] ?? 'ASC');\n                    }\n\n                    $mapping['orderBy'] = $orderBy;\n                }\n\n                if (isset($oneToManyElement['index-by'])) {\n                    $mapping['indexBy'] = (string) $oneToManyElement['index-by'];\n                } elseif (isset($oneToManyElement->{'index-by'})) {\n                    throw new InvalidArgumentException('<index-by /> is not a valid tag');\n                }\n\n                // Evaluate second level cache\n                if (isset($oneToManyElement->cache)) {\n                    $mapping['cache'] = $metadata->getAssociationCacheDefaults($mapping['fieldName'], $this->cacheToArray($oneToManyElement->cache));\n                }\n\n                $metadata->mapOneToMany($mapping);\n            }\n        }\n\n        // Evaluate <many-to-one ...> mappings\n        if (isset($xmlRoot->{'many-to-one'})) {\n            foreach ($xmlRoot->{'many-to-one'} as $manyToOneElement) {\n                $mapping = [\n                    'fieldName' => (string) $manyToOneElement['field'],\n                ];\n","sourceCodeStart":401,"sourceCodeEnd":437,"githubUrl":"https://github.com/doctrine/orm/blob/d9b9ff73016bf598ae07515f97289ce8074e97a5/src/Mapping/Driver/XmlDriver.php#L401-L437","documentation":"In Doctrine XML mappings, index-by is an XML attribute on the <one-to-many> element (index-by=\"fieldName\"), not a child element. If the parser finds a nested <index-by> tag, it throws InvalidArgumentException because the child form has never been valid for one-to-many collections.","triggerScenarios":"Writing <one-to-many field=\"phonenumbers\" target-entity=\"Phonenumber\"><index-by>name</index-by></one-to-many> instead of putting index-by on the element itself. Happens in hand-edited or machine-converted .dcm.xml files.","commonSituations":"Migrating old Symfony 1 / Doctrine 1 style YAML/XML where index-by appeared as a child; XSD validation disabled so the invalid structure is not caught at load; developers copying snippet templates from old blog posts.","solutions":["Move the value onto the element as an attribute: <one-to-many field=\"phonenumbers\" target-entity=\"Phonenumber\" index-by=\"name\" />.","Re-enable XSD validation (default) so invalid structures fail early with a schema error instead.","Validate your .dcm.xml files in CI against doctrine-mapping.xsd."],"exampleFix":"<!-- before -->\n<one-to-many field=\"phonenumbers\" target-entity=\"Phonenumber\">\n    <index-by>name</index-by>\n</one-to-many>\n\n<!-- after -->\n<one-to-many field=\"phonenumbers\" target-entity=\"Phonenumber\" index-by=\"name\" />","handlingStrategy":"validation","validationCode":"// Keep XSD validation on: it rejects child <index-by> at load time.\n$driver = new XmlDriver($locator); // isXsdValidationEnabled = true (default)\n// plus CI: xmllint --noout --schema doctrine-mapping.xsd src/Entity/*.dcm.xml","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remember: in Doctrine XML, index-by/order-by attributes go on the element, not child tags.","Validate all .dcm.xml files against the shipped XSD in CI.","Prefer converting to attribute mappings to eliminate XML-shape mistakes."],"tags":["doctrine-orm","xml-mapping","one-to-many","index-by"],"backgroundTag":"invalid-mapping-file","analyzedSha":"d9b9ff73016bf598ae07515f97289ce8074e97a5","analyzedAt":"2026-08-21T06:13:15.863Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}