{"record":{"id":"2c34ec53fc5db377","repo":"symfony/symfony","slug":"cannot-find-mapping-for-s-declare-one-using-ei","errorCode":null,"errorMessage":"Cannot find mapping for \"%s\": declare one using either the #[MapEntity] attribute or mapped route parameters.","messagePattern":"Cannot find mapping for \"(.+?)\": declare one using either the #\\[MapEntity\\] attribute or mapped route parameters\\.","errorType":"exception","errorClass":"Symfony\\Component\\HttpKernel\\Exception\\NearMissValueResolverException","httpStatus":null,"severity":"error","filePath":"src/Symfony/Bridge/Doctrine/ArgumentResolver/EntityValueResolver.php","lineNumber":76,"sourceCode":"        if (!$manager = $this->getManager($this->registry, $options->objectManager, $options->class)) {\n            return [];\n        }\n\n        $message = '';\n        if (null !== $options->expr) {\n            $variables = array_merge($request->attributes->all(), ['request' => $request]);\n            if (null === $object = $this->findViaExpression($this->expressionLanguage, $manager, $options, $variables)) {\n                $message = \\sprintf(' The expression \"%s\" returned null.', $options->expr);\n            }\n        // find by identifier?\n        } elseif (false === $object = $this->findById($manager, $options, $this->getIdentifier($request, $options, $argument))) {\n            // find by criteria\n            if (!$criteria = $this->getCriteria($request, $options, $manager, $argument)) {\n                if (!class_exists(NearMissValueResolverException::class)) {\n                    return [];\n                }\n\n                throw new NearMissValueResolverException(\\sprintf('Cannot find mapping for \"%s\": declare one using either the #[MapEntity] attribute or mapped route parameters.', $options->class));\n            }\n            $object = $this->findOneByCriteria($manager, $options, $criteria);\n        }\n\n        if (null === $object && !$argument->isNullable()) {\n            throw new NotFoundHttpException($options->message ?? (\\sprintf('\"%s\" object not found by \"%s\".', $options->class, self::class).$message));\n        }\n\n        return [$object];\n    }\n\n    private function getIdentifier(Request $request, MapEntity $options, ArgumentMetadata $argument): mixed\n    {\n        if (\\is_array($options->id)) {\n            $id = [];\n            foreach ($options->id as $field) {\n                // Convert \"%s_uuid\" to \"foobar_uuid\"\n                if (str_contains($field, '%s')) {","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/symfony/symfony/blob/698e28026c22cf35d032cdb6e800db48b1535790/src/Symfony/Bridge/Doctrine/ArgumentResolver/EntityValueResolver.php#L58-L94","documentation":"The HTTP EntityValueResolver throws this NearMissValueResolverException when a controller argument is type-hinted as a Doctrine entity but the resolver cannot find any identifier or criteria for it — neither from a #[MapEntity] attribute nor from route parameters mapped to the argument. It differs from a 404: a 404 means the query ran and returned nothing; this means the resolver never figured out how to query, so the developer must declare the mapping.","triggerScenarios":"A controller action has a parameter typed as an entity (e.g. `function show(User $user)`) with no #[MapEntity] attribute, no route parameter named 'user', no route parameter named 'id', and no '_route_mapping' entry. findById() returns false and getCriteria() returns [], so line 76 throws.","commonSituations":"Adding an entity controller argument but forgetting to add the matching {user} route placeholder; renaming the argument without updating the route; expecting criteria from multiple route params without configuring #[MapEntity(mapping: [...])].","solutions":["Add a route parameter with the same name as the argument (e.g. {user}) so findById/getCriteria can use it.","Add #[MapEntity] with explicit 'id' or 'mapping' to declare which request attributes identify the entity.","If an 'id' route parameter exists for a different argument, rely on the automatic 'id' fallback or set #[MapEntity(id: 'user_id')].","Make the argument nullable if the entity is optional."],"exampleFix":"// before\n#[Route('/users/show', name: 'user_show')]\npublic function show(User $user): Response { }\n\n// after\n#[Route('/users/{user}/show', name: 'user_show')]\npublic function show(#[MapEntity] User $user): Response { }","handlingStrategy":"validation","validationCode":"// Ensure the route exposes a placeholder matching the argument or 'id'.\n$route = $collection->get('user_show');\n$needs = ['user', 'id'];\nif (!array_intersect($needs, $route->getRequirements() ? array_keys($route->getDefaults()) : [])) {\n    throw new \\LogicException('Add a {user} (or {id}) route param or a #[MapEntity].');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the route placeholder name in sync with the controller argument name.","Add #[MapEntity(id:)] or #[MapEntity(mapping:)] for non-standard parameter names.","Write a controller test that asserts the route resolves the entity."],"tags":["doctrine","http","argument-resolver","map-entity","configuration"],"analyzedSha":"698e28026c22cf35d032cdb6e800db48b1535790","analyzedAt":"2026-08-06T23:40:49.025Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}