TencentCloud/TencentDB-Agent-Memory · error · MetadataError

user_key_not_found

user_key_not_found

Error message

user key not found: ${keyId}

What it means

MetadataError code 'user_key_not_found' thrown by getUserKey when store.getUserKeyById(keyId) returns no entity. The key id passed in does not correspond to any stored user key — it may have been revoked/deleted, belong to another environment, or simply be mistyped. The message includes the offending keyId for debugging.

Source

Thrown at MemoryCore/src/metadata/service/metadata-service.ts:713

    const entity = await this.store.createUserKey({
      user_id: userId,
      name: input.name,
      expires_at: input.expires_at,
      is_default: false,
    });
    return { ...this.toPublicUserKey(entity), key_value: entity.key_value };
  }

  async listUserKeys(userId: string, pagination: PaginationParams = DEFAULT_PAGINATION): Promise<PaginatedResult<UserKeyPublic>> {
    await this.requireUser(userId);
    const page = await this.store.listUserKeys(userId, pagination);
    const items = page.items.map((k) => this.toPublicUserKey(k));
    return formatListResult({ items, total: page.total }, pagination);
  }

  async getUserKey(keyId: string): Promise<UserKeyPublic> {
    const entity = await this.store.getUserKeyById(keyId);
    if (!entity) throw new MetadataError("user_key_not_found", `user key not found: ${keyId}`);
    return this.toPublicUserKey(entity);
  }

  /** 校验调用方有权访问该 key（本人、system_admin 或 bootstrap），返回脱敏详情。 */
  async getUserKeyForCaller(
    keyId: string,
    callerUserId?: string,
    isAdmin = false,
    isSystemAdmin = false,
  ): Promise<UserKeyPublic> {
    const entity = await this.store.getUserKeyById(keyId);
    if (!entity) throw new MetadataError("user_key_not_found", `user key not found: ${keyId}`);
    const owner = await this.getUserById(entity.user_id);
    if (!owner) {
      throw new MetadataError("user_key_not_found", `user key not found: ${keyId}`);
    }
    if (!isAdmin && !isSystemAdmin && entity.user_id !== callerUserId) {
      throw new MetadataError("permission_denied", "cannot access another user's key");

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Verify the keyId is correct and complete (check for truncation/whitespace) and that you are hitting the intended environment.
2. List the user's current keys first and pick the id from that list instead of a cached value.
3. If the key was revoked, create a new key rather than looking up the old one.
4. Catch MetadataError code 'user_key_not_found' and treat it as 404, refreshing key lists client-side.

Example fix

// before
const key = await service.getUserKey(cachedKeyId); // revoked earlier
// after
const { items } = await service.listUserKeysForCaller(userId, ctx);
const key = items.find(k => k.name === 'ci') ?? await service.createUserKeyForCaller(userId, ctx, { name: 'ci' });

const { items } = await service.listUserKeysForCaller(userId, ctx);
const exists = items.some(k => k.id === keyId);
if (!exists) { /* refresh id or create a new key */ }

function isKnownKey(keyId: string, items: { id: string }[]): boolean {
  return items.some(k => k.id === keyId);
}

try {
  await service.getUserKey(keyId);
} catch (e) {
  if (e instanceof MetadataError && e.code === 'user_key_not_found') { /* treat as 404: refresh list or recreate key */ }
  throw e;
}

When it happens

Trigger: Calling getUserKey(keyId) (or getUserKeyForCaller built on it) with an id that is absent from the store: already-revoked keys, deleted keys, ids from a different deployment/database, or truncated/malformed ids.

Common situations: Client cached a key id that an admin later revoked; copy-paste dropped characters from the id; staging key id used against production; hard delete during a cleanup job while the client still references it.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• user_not_found
• key_limit_exceeded
• task_not_found

AI-assisted analysis of TencentCloud/TencentDB-Agent-Memory@3efcd317b8 (2026-09-01). Data as JSON: /api/errors/f22fca623e2b04d0. Report an issue: GitHub.