TencentCloud/TencentDB-Agent-Memory · error · MetadataError

user_not_found

user_not_found

Error message

user not found: ${userId}

What it means

requireUser is a private guard in MetadataService used before user-scoped operations such as createUserKey and listUserKeys. It loads the user by id via getUserById and throws user_not_found (a not_found MetadataError) when no user record matches, preventing key operations against nonexistent users.

Source

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

    }
    return out;
  }

  /** internal：按实例分页列出用户（含 system_admin，不脱敏）。 */
  async listUsersByInstance(
    instanceId: string,
    pagination: PaginationParams,
    filter?: InstanceUserListFilter,
  ): Promise<PaginatedResult<UserEntity>> {
    void instanceId;
    const page = await this.store.listUsers(pagination, filter);
    return formatListResult(page, pagination);
  }

  /** 校验用户存在，否则抛 not_found。 */
  private async requireUser(userId: string): Promise<UserEntity> {
    const user = await this.getUserById(userId);
    if (!user) throw new MetadataError("user_not_found", `user not found: ${userId}`);
    return user;
  }

  get rawStore(): IMetadataStore {
    return this.store;
  }

  private async assertUserQuota(): Promise<void> {
    const count = await this.store.countUsers();
    const limit = this._configParams
      ? await this._configParams.getEffectiveInt("quota", "max_users_per_instance")
      : this.quota.maxUsersPerInstance;
    if (count >= limit) {
      throw new MetadataError(
        "user_limit_exceeded",
        `user limit ${limit} reached for instance ${this.instanceId} (current: ${count})`,
      );
    }

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Verify the userId exists (query the users table / getUserById) before creating or listing keys.
2. Re-fetch the correct user id — the record may have been deleted or the id may come from the wrong environment.
3. Confirm the service is pointed at the same database/tenant where the user was created.
4. Catch MetadataError with code 'user_not_found' and return a 404-style response to the API caller.

Example fix

// before
await metadataService.createUserKey(unknownId, { name: "key" });
// after — check existence first
const user = await metadataService.getUserById(unknownId);
if (!user) throw new NotFoundError(`user not found: ${unknownId}`);
await metadataService.createUserKey(unknownId, { name: "key" });

const user = await metadataService.getUserById(userId);
if (!user) throw new NotFoundError(`user not found: ${userId}`);
await metadataService.createUserKey(userId, keySpec);

try {
  keys = await metadataService.listUserKeys(userId, pagination);
} catch (e) {
  if (e instanceof MetadataError && e.code === "user_not_found") {
    return res.status(404).json({ error: `user ${userId} does not exist` });
  }
  throw e;
}

When it happens

Trigger: createUserKey(userId, ...) or listUserKeys(userId, ...) called with a userId that has no row in the metadata store (deleted user, wrong id, wrong tenant/database).

Common situations: Using a stale user id after the user was deleted, passing an id from a different environment (prod id against dev DB), copy-paste of a truncated or wrong-kind identifier, or users created outside this metadata store.

Understand the failure class

Background: "User not found", "Invalid user", and "does not exist": what missing-user lookup errors mean across Rocket.Chat, LiteLLM, Phabricator, rustfs, and pnpm — this error's family across 10 libraries.

Related errors

• user_key_not_found
• task_not_found

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