{"record":{"id":"f22fca623e2b04d0","repo":"TencentCloud/TencentDB-Agent-Memory","slug":"user-key-not-found-f22fca","errorCode":"user_key_not_found","errorMessage":"user key not found: ${keyId}","messagePattern":"user key not found: (.+?)","errorType":"error_code","errorClass":"MetadataError","httpStatus":null,"severity":"error","filePath":"MemoryCore/src/metadata/service/metadata-service.ts","lineNumber":713,"sourceCode":"    const entity = await this.store.createUserKey({\n      user_id: userId,\n      name: input.name,\n      expires_at: input.expires_at,\n      is_default: false,\n    });\n    return { ...this.toPublicUserKey(entity), key_value: entity.key_value };\n  }\n\n  async listUserKeys(userId: string, pagination: PaginationParams = DEFAULT_PAGINATION): Promise<PaginatedResult<UserKeyPublic>> {\n    await this.requireUser(userId);\n    const page = await this.store.listUserKeys(userId, pagination);\n    const items = page.items.map((k) => this.toPublicUserKey(k));\n    return formatListResult({ items, total: page.total }, pagination);\n  }\n\n  async getUserKey(keyId: string): Promise<UserKeyPublic> {\n    const entity = await this.store.getUserKeyById(keyId);\n    if (!entity) throw new MetadataError(\"user_key_not_found\", `user key not found: ${keyId}`);\n    return this.toPublicUserKey(entity);\n  }\n\n  /** 校验调用方有权访问该 key（本人、system_admin 或 bootstrap），返回脱敏详情。 */\n  async getUserKeyForCaller(\n    keyId: string,\n    callerUserId?: string,\n    isAdmin = false,\n    isSystemAdmin = false,\n  ): Promise<UserKeyPublic> {\n    const entity = await this.store.getUserKeyById(keyId);\n    if (!entity) throw new MetadataError(\"user_key_not_found\", `user key not found: ${keyId}`);\n    const owner = await this.getUserById(entity.user_id);\n    if (!owner) {\n      throw new MetadataError(\"user_key_not_found\", `user key not found: ${keyId}`);\n    }\n    if (!isAdmin && !isSystemAdmin && entity.user_id !== callerUserId) {\n      throw new MetadataError(\"permission_denied\", \"cannot access another user's key\");","sourceCodeStart":695,"sourceCodeEnd":731,"githubUrl":"https://github.com/TencentCloud/TencentDB-Agent-Memory/blob/3efcd317b84146d6a08518ac0f7ee7c8a8d200ec/MemoryCore/src/metadata/service/metadata-service.ts#L695-L731","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the keyId is correct and complete (check for truncation/whitespace) and that you are hitting the intended environment.","List the user's current keys first and pick the id from that list instead of a cached value.","If the key was revoked, create a new key rather than looking up the old one.","Catch MetadataError code 'user_key_not_found' and treat it as 404, refreshing key lists client-side."],"exampleFix":"// before\nconst key = await service.getUserKey(cachedKeyId); // revoked earlier\n// after\nconst { items } = await service.listUserKeysForCaller(userId, ctx);\nconst key = items.find(k => k.name === 'ci') ?? await service.createUserKeyForCaller(userId, ctx, { name: 'ci' });","handlingStrategy":"try-catch","validationCode":"const { items } = await service.listUserKeysForCaller(userId, ctx);\nconst exists = items.some(k => k.id === keyId);\nif (!exists) { /* refresh id or create a new key */ }","typeGuard":"function isKnownKey(keyId: string, items: { id: string }[]): boolean {\n  return items.some(k => k.id === keyId);\n}","tryCatchPattern":"try {\n  await service.getUserKey(keyId);\n} catch (e) {\n  if (e instanceof MetadataError && e.code === 'user_key_not_found') { /* treat as 404: refresh list or recreate key */ }\n  throw e;\n}","preventionTips":["Fetch key ids from list calls instead of caching them indefinitely","Handle revocation events so cached ids are invalidated","Validate id format (length/charset) before calling to catch truncation","Keep environments separated to avoid cross-env id lookups"],"tags":["not-found","key-management"],"backgroundTag":"resource-not-found","analyzedSha":"3efcd317b84146d6a08518ac0f7ee7c8a8d200ec","analyzedAt":"2026-09-01T05:44:22.276Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}