symfony/symfony · error · Symfony\Component\HttpKernel\Exception\NearMissValueResolverException

Cannot find mapping for "%s": declare one using either the #

Error message

Cannot find mapping for "%s": declare one using either the #[MapEntity] attribute or mapped route parameters.

What it means

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.

Source

Thrown at src/Symfony/Bridge/Doctrine/ArgumentResolver/EntityValueResolver.php:76

        if (!$manager = $this->getManager($this->registry, $options->objectManager, $options->class)) {
            return [];
        }

        $message = '';
        if (null !== $options->expr) {
            $variables = array_merge($request->attributes->all(), ['request' => $request]);
            if (null === $object = $this->findViaExpression($this->expressionLanguage, $manager, $options, $variables)) {
                $message = \sprintf(' The expression "%s" returned null.', $options->expr);
            }
        // find by identifier?
        } elseif (false === $object = $this->findById($manager, $options, $this->getIdentifier($request, $options, $argument))) {
            // find by criteria
            if (!$criteria = $this->getCriteria($request, $options, $manager, $argument)) {
                if (!class_exists(NearMissValueResolverException::class)) {
                    return [];
                }

                throw new NearMissValueResolverException(\sprintf('Cannot find mapping for "%s": declare one using either the #[MapEntity] attribute or mapped route parameters.', $options->class));
            }
            $object = $this->findOneByCriteria($manager, $options, $criteria);
        }

        if (null === $object && !$argument->isNullable()) {
            throw new NotFoundHttpException($options->message ?? (\sprintf('"%s" object not found by "%s".', $options->class, self::class).$message));
        }

        return [$object];
    }

    private function getIdentifier(Request $request, MapEntity $options, ArgumentMetadata $argument): mixed
    {
        if (\is_array($options->id)) {
            $id = [];
            foreach ($options->id as $field) {
                // Convert "%s_uuid" to "foobar_uuid"
                if (str_contains($field, '%s')) {

View on GitHub (pinned to 698e28026c)

Solutions

1. Add a route parameter with the same name as the argument (e.g. {user}) so findById/getCriteria can use it.
2. Add #[MapEntity] with explicit 'id' or 'mapping' to declare which request attributes identify the entity.
3. If an 'id' route parameter exists for a different argument, rely on the automatic 'id' fallback or set #[MapEntity(id: 'user_id')].
4. Make the argument nullable if the entity is optional.

Example fix

// before
#[Route('/users/show', name: 'user_show')]
public function show(User $user): Response { }

// after
#[Route('/users/{user}/show', name: 'user_show')]
public function show(#[MapEntity] User $user): Response { }

// Ensure the route exposes a placeholder matching the argument or 'id'.
$route = $collection->get('user_show');
$needs = ['user', 'id'];
if (!array_intersect($needs, $route->getRequirements() ? array_keys($route->getDefaults()) : [])) {
    throw new \LogicException('Add a {user} (or {id}) route param or a #[MapEntity].');
}

When it happens

Trigger: 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.

Common situations: 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: [...])].

Related errors

• Cannot find mapping for "%s": use the #[MapEntity] attribute
• You cannot use the "%s" if the ExpressionLanguage component
• The "id" and "mapping" options cannot be used together on #[
• The "id" and "exclude" options cannot be used together on #[
• "%s" object not found by "%s".%s

AI-assisted analysis of symfony/symfony@698e28026c (2026-08-06). Data as JSON: /api/errors/2c34ec53fc5db377. Report an issue: GitHub.