passbolt/passbolt_api · error · NotFoundException

Entity not found.

Error message

Entity {0} not found.

What it means

validateMany loads all entities referenced by the batch IDs from the database and re-indexes them by ID. When an entry's ID is not found among the loaded entities, it throws NotFoundException('Entity {0} not found.'). This means the referenced resource or folder does not exist (or is not visible to the requesting user).

Solutions

1. Verify the entity exists with the exact UUID (GET /resources/<id>.json or /folders/<id>.json) before including it in the batch.
2. Remove stale/deleted IDs from the batch payload and resubmit.
3. Check the authenticated user's permissions (ARE) on the entities — the lookup is permission-filtered.
4. Confirm you are querying the intended instance/database (avoid mixing exported IDs across environments).

Example fix

// before (id from another instance, not found)
[{"id": "11111111-1111-1111-1111-111111111111", ...}]

// after (fetch fresh IDs first)
$resources = json_decode(file_get_contents($url . '/resources.json?contain[id]=1'), true);
$ids = array_column($resources, 'id');

$existing = $resourcesTable->find('list', ['keyField' => 'id'])
    ->where(['id IN' => array_column($batch, 'id')])->toArray();
$missing = array_diff(array_column($batch, 'id'), array_keys($existing));
if ($missing) {
    throw new InvalidArgumentException('Unknown ids: ' . implode(', ', $missing));
}

function allEntitiesExist(array $ids, callable $lookup): bool {
    return empty(array_diff($ids, $lookup($ids)));
}

try {
    $data = $service->validateMany($requestData);
} catch (NotFoundException $e) {
    // parse the missing id from the message, drop it from the batch, and resubmit
}

When it happens

Trigger: Batch metadata update requests containing an `id` that matches no accessible resource/folder row — deleted entities, wrong database, IDs from another instance, or soft-deleted/permission-filtered records.

Common situations: Migrating batches exported from one passbolt instance into another; concurrent deletion of a resource between listing and updating; stale client caches holding IDs of removed folders/resources; missing permission on the entity so the query excludes it.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Could not validate the metadata key data for the entity…
• The entity must be an array.
• The folder does not exist.
• The identifier should be a valid UUID.
• The metadata key does not exist or has been deleted.

AI-assisted analysis of passbolt/passbolt_api@31c1bbc10f (2026-09-17). Data as JSON: /api/errors/116bc320e0cbb052. Report an issue: GitHub.

Appendix: source

Thrown at plugins/PassboltCe/Metadata/src/Model/Validation/MetadataBatchUpdateValidationService.php:76

            }

            $id = $values['id'] ?? null;
            if (!Validation::uuid($id)) {
                throw new BadRequestException(__('The identifier should be a valid UUID.'));
            }
        }

        $entityIds = Hash::extract($requestData, '{n}.id');
        $this->entities = $this->queryEntitiesFromIds($entityIds)->all()->toArray();
        // Re-arrange entities array to set key as identifier and value as entity object to easily find it
        $this->entities = Hash::combine($this->entities, '{n}.id', '{n}');

        $data = [];
        $errors = [];
        foreach ($requestData as $i => $entity) {
            $entityId = $entity['id'];
            if (!array_key_exists($entityId, $this->entities)) {
                throw new NotFoundException(__('Entity {0} not found.', $entityId));
            }

            /** @var \Passbolt\Metadata\Model\Entity\MetadataKey|null $metadataKey */
            $metadataKey = $this->entities[$entityId]['metadata_key'] ?? null;
            if (!is_null($metadataKey)) {
                $metadataKey = $metadataKey->toArray();
            }
            $entity['metadata_key'] = $metadataKey;
            $entity = $this->setMetadataKeyIdIfNotDefinedAndEntityIsPersonal($entity);

            $form = $this->getForm();
            if (!$form->execute($entity)) {
                $errors[$i] = $form->getErrors();
                throw new CustomValidationException(__('Could not validate the metadata key data for the entity with ID: {0}.', $entityId), $errors); // phpcs:ignore;
            }
            $data[$i] = $form->getData();
        }

View on GitHub (pinned to 31c1bbc10f)