passbolt/passbolt_api · error · Exception

The avatar id is not valid.

Error message

The avatar id is not valid.

What it means

AvatarsCacheService builds the cache directory from the avatar's UUID id. getOrCreateAvatarDirectory throws a plain Exception('The avatar id is not valid.') if the id is not a valid UUID, since it is used as a filesystem path component.

Solutions

1. Persist the Avatar entity before generating cache files so it gets a UUID id.
2. Fix the data source so avatar.id contains valid UUIDs (repair migration or fixture).
3. Check the code path that constructs the Avatar and ensure the id is populated.

Example fix

// before
$avatar = new Avatar(['user_id' => $userId]);
$service->getSmallAvatarFileName($avatar); // id null
// after
$avatar = $avatarsTable->save(new Avatar(['user_id' => $userId]));
$service->getSmallAvatarFileName($avatar);

if ($avatar->id === null || !\Cake\Validation\Validation::uuid($avatar->id)) {
    // persist the avatar or abort before generating cache files
}

function hasValidAvatarId(\App\Model\Entity\Avatar $a): bool {
    return $a->id !== null && \Cake\Validation\Validation::uuid($a->id);
}

try {
    $fileName = $service->getSmallAvatarFileName($avatar);
} catch (\Exception $e) {
    Log::error('Invalid avatar id: ' . $e->getMessage());
    return $defaultAvatar;
}

When it happens

Trigger: Reading/exporting avatar files for an Avatar entity whose id is null, empty, or not a UUID (unsaved entity, bad fixture, corrupted row).

Common situations: Rendering an avatar built in memory before persistence; import/migration scripts inserting avatars without UUID ids; test fixtures with fixed non-UUID ids.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• Cannot generate a random UUID, some dependencies are…
• Record not found
• The authentication token id is invalid.
• The request data is invalid: id invalid.
• The SCIM setting identifier should be a valid UUID.

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

Appendix: source

Thrown at src/Service/Avatars/AvatarsCacheService.php:225

    {
        return $this->getOrCreateAvatarDirectory($avatar)
            . AvatarsConfigurationService::FORMAT_MEDIUM
            . AvatarHelper::IMAGE_EXTENSION;
    }

    /**
     * Get or create the relative directory name of a given avatar.
     *
     * @param \App\Model\Entity\Avatar $avatar Avatar
     * @return string
     * @throws \League\Flysystem\FilesystemException The cache directory must be readable/writable.
     * @throws \Exception if the avatar id is not a uuid.
     */
    protected function getOrCreateAvatarDirectory(Avatar $avatar): string
    {
        $avatarId = $avatar->id;
        if (!Validation::uuid($avatarId)) {
            throw new Exception(__('The avatar id is not valid.'));
        }
        $avatarCacheSubDirectory = $avatarId . DS;
        $this->filesystem->createDirectory($avatarCacheSubDirectory);

        return $avatarCacheSubDirectory;
    }

    /**
     * The default avatar format
     *
     * @return string
     */
    protected function getDefaultFormat(): string
    {
        return AvatarsConfigurationService::FORMAT_MEDIUM;
    }
}

View on GitHub (pinned to 31c1bbc10f)