TencentCloud/TencentDB-Agent-Memory · error · MetadataError

missing_team_id

missing_team_id

Error message

team_id is required for non-system-admin callers

What it means

MetadataError code 'missing_team_id' thrown by listUsersForCaller when a paginated user list is requested without a team_id filter. The library restricts team-less global user listing to system administrators; every other caller must scope the query to a team. It exists to prevent non-admin users from enumerating all users in the system.

Source

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

    }
    return this.deleteUsers(userIds);
  }

  async deleteUsers(userIds: string[]): Promise<BatchDeleteResult> {
    return this.store.deleteUsers(userIds);
  }

  async listUsersForCaller(
    input: { team_id?: string } & UserListFilter,
    ctx: V3AuthContext,
    pagination: PaginationParams,
  ): Promise<PaginatedResult<UserPublic>> {
    const filtersPresent = !!(input.user_ids?.length || input.username);
    const storeFilter = this.buildUserListStoreFilter(input);

    if (!input.team_id) {
      if (!ctx.isSystemAdmin) {
        throw new MetadataError("missing_team_id", "team_id is required for non-system-admin callers");
      }
      const page = await this.store.listUsers(pagination, storeFilter);
      const items = filterVisibleUsers(page.items, ctx);
      return formatListResult({ items, total: page.total }, pagination);
    }

    const teamId = input.team_id;

    if (ctx.isSystemAdmin) {
      const page = await this.store.listUsersByTeam(teamId, pagination, storeFilter);
      const items = filterVisibleUsers(page.items, ctx);
      return formatListResult({ items, total: page.total }, pagination);
    }

    if (!ctx.userId) {
      throw new MetadataError("permission_denied", "authentication required");
    }

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Add team_id to the input passed to listUsersForCaller / listUsersByTeamForCaller so the query is team-scoped.
2. If a global listing is truly intended, elevate the caller's auth context to isSystemAdmin=true (valid system admin credential).
3. Split the request into per-team requests, one per team the caller belongs to, and merge results client-side.
4. Wrap the call in error handling for MetadataError with code 'missing_team_id' and surface a actionable message to the caller.

Example fix

// before
await service.listUsersForCaller(ctx, { username: 'alice' }, pagination);
// after
await service.listUsersForCaller(ctx, { team_id: teamId, username: 'alice' }, pagination);

function canList(input, ctx) { return Boolean(input.team_id) || ctx.isSystemAdmin; }
if (!canList(input, ctx)) throw new Error('Provide team_id or use a system-admin context');

function hasTeamScope(input): input is typeof input & { team_id: string } {
  return typeof input.team_id === 'string' && input.team_id.length > 0;
}

try {
  await service.listUsersForCaller(ctx, input, pagination);
} catch (e) {
  if (e instanceof MetadataError && e.code === 'missing_team_id') { /* re-scope to a team or elevate ctx */ }
  throw e;
}

When it happens

Trigger: Calling listUsersForCaller (directly or via listUsersByTeamForCaller) with an input object whose team_id is undefined/empty while the V3AuthContext has isSystemAdmin=false. E.g. passing only {username} or {user_ids:[...]} filters with no team_id.

Common situations: Forgetting to set team_id in the list request after migrating from an admin-only API; a client builds the filter dynamically and omits team_id when no team filter is checked in the UI; a service account that was downgraded from system_admin still issues global user-list calls.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• filter_not_allowed
• memory 系统用户 key 必须匹配 sk-mem-[A-Za-z0-9_-]{32}
• llm.provider=proxy 且 useMemorySystemUserKey=false 时必须显式 llm.
• Generation log object key exceeds COS limit
• Invalid generation log key

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