appwrite/appwrite · error · Appwrite\Exception

KEY_ALREADY_EXISTS

KEY_ALREADY_EXISTS

Error message

KEY_ALREADY_EXISTS

What it means

Thrown when updating a project key triggers a Duplicate exception from the database adapter during updateDocument, mapped to key_already_exists. On update this fires when a changed unique attribute (e.g. the key's $id/ID field) collides with another key document, not when merely editing name or scopes.

Solutions

  1. Ensure the update does not change the key's ID to an existing one; only update name/scopes/expire.
  2. Choose a different unique value or delete the conflicting key first.
  3. Use ID.unique() when generating replacement identifiers.
  4. List keys first to detect the conflicting ID before issuing the update.

Example fix

// before
await organization.updateProjectKey(projectId, keyId, name, scopes); // keyId changed to existing id
// after
await organization.updateProjectKey(projectId, existingKeyId, name, scopes); // update in place, keep original ID
Defensive patterns

Strategy: try-catch

Validate before calling

const keys = await organization.listProjectKeys(projectId);
if (keys.keys.some(k => k.$id === newId && k.$id !== currentKeyId)) throw new Error(`ID ${newId} conflicts with another key`);

Try / catch

try {
  await organization.updateProjectKey(projectId, keyId, name, scopes);
} catch (e) {
  if (e.code === 409) { /* unique-field collision: choose another ID or update in place */ }
  else throw e;
}

Prevention

When it happens

Trigger: PATCH /v1/organization/projects/:projectId/keys/:keyId where the update payload changes a unique field to a value already held by another key in the 'keys' collection (e.g. renaming an ID to one that exists).

Common situations: Automation that renames/re-ids keys to a deterministic value already used; merging two environments where both contain a key with the same identifier; retry logic replaying an update that partially succeeded under a new ID.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors


AI-assisted analysis of appwrite/appwrite@ca3c55abfe (2026-09-16). Data as JSON: /api/errors/e5d12ff624382ae8. Report an issue: GitHub.

Appendix: source

Thrown at src/Appwrite/Platform/Modules/Organization/Http/Projects/Keys/Update.php:111

        // The request may run through the console project; events and audits belong to the resolved project
        $queueForEvents->setProject($project);
        $auditContext->project = $project;
        $key = $authorization->skip(fn () => $dbForPlatform->getDocument('keys', $keyId));

        if ($key->isEmpty() || $key->getAttribute('resourceType', '') !== 'projects' || $key->getAttribute('resourceInternalId', '') !== $project->getSequence()) {
            throw new Exception(Exception::KEY_NOT_FOUND);
        }

        $updates = new Document([
            'name' => $name,
            'scopes' => $scopes,
            'expire' => $expire,
        ]);

        try {
            $key = $authorization->skip(fn () => $dbForPlatform->updateDocument('keys', $key->getId(), $updates));
        } catch (Duplicate) {
            throw new Exception(Exception::KEY_ALREADY_EXISTS);
        }

        $authorization->skip(fn () => $dbForPlatform->purgeCachedDocument('projects', $project->getId()));

        $queueForEvents->setParam('keyId', $key->getId());

        $response->dynamic($key, Response::MODEL_KEY);
    }
}

View on GitHub (pinned to ca3c55abfe)