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
- Ensure the update does not change the key's ID to an existing one; only update name/scopes/expire.
- Choose a different unique value or delete the conflicting key first.
- Use ID.unique() when generating replacement identifiers.
- 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
- Update name/scopes/expire in place; do not change unique identifiers on update.
- Check for conflicting IDs before issuing updates that alter identifiers.
- Clean up duplicate deterministic keys when merging environments.
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
- key_already_exists
- collection_already_exists
- database_already_exists
- document_already_exists
- document_already_exists
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)