TencentCloud/TencentDB-Agent-Memory · error · MetadataError

filter_not_allowed

filter_not_allowed

Error message

filters are not allowed for normal team members

What it means

MetadataError code 'filter_not_allowed' thrown by listUsersForCaller when a plain (non-admin) team member supplies list filters (user_ids or username). Ordinary team members may only fetch the paginated member list unfiltered; targeted lookups by id/username are reserved for team admins and system admins.

Source

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

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

    const member = await this.store.getTeamMember(teamId, ctx.userId);
    if (!member || member.status !== "active") {
      throw new MetadataError("permission_denied", "not a team member");
    }

    const isTeamAdmin = member.role === "admin";
    if (isTeamAdmin) {
      const page = await this.store.listUsersByTeam(teamId, pagination, storeFilter);
      const items = filterVisibleUsers(page.items, ctx, { allowTeamPeers: true });
      return formatListResult({ items, total: page.total }, pagination);
    }

    if (filtersPresent) {
      throw new MetadataError("filter_not_allowed", "filters are not allowed for normal team members");
    }

    const self = await this.store.getUserById(ctx.userId);
    if (!self) {
      throw new MetadataError("user_not_found", `user not found: ${ctx.userId}`);
    }
    const visible = filterVisibleUsers([self], ctx);
    if (pagination.offset > 0) {
      return wrapPaginated([], 1, pagination);
    }
    return wrapPaginated(visible, 1, pagination);
  }

  private buildUserListStoreFilter(input: UserListFilter): InstanceUserListFilter | undefined {
    const filter: InstanceUserListFilter = {};
    if (input.user_ids?.length) filter.user_ids = input.user_ids;
    if (input.username) filter.username = input.username;
    return Object.keys(filter).length ? filter : undefined;

View on GitHub (pinned to 3efcd317b8)

Solutions

1. Remove user_ids/username filters from the request and iterate the paginated member list client-side instead.
2. Elevate the caller to team admin (member.role === 'admin') if targeted lookups are genuinely needed.
3. Have a system admin run the filtered query.
4. Catch MetadataError code 'filter_not_allowed' and fall back to the unfiltered list with client-side filtering.

Example fix

// before
await service.listUsersForCaller(ctx, { team_id: 't1', username: 'bob' }, pagination);
// after (member caller)
await service.listUsersForCaller(ctx, { team_id: 't1' }, pagination); // filter client-side

const filtersPresent = !!(input.user_ids?.length || input.username);
if (filtersPresent && !ctx.isSystemAdmin && member?.role !== 'admin') {
  // drop filters and filter client-side, or reject before the call
}

function mayFilter(ctx: V3AuthContext, member?: { role: string } | null): boolean {
  return ctx.isSystemAdmin || member?.role === 'admin';
}

try {
  return await service.listUsersForCaller(ctx, input, pagination);
} catch (e) {
  if (e instanceof MetadataError && e.code === 'filter_not_allowed') {
    return await service.listUsersForCaller(ctx, { team_id: input.team_id }, pagination); // unfiltered fallback
  }
  throw e;
}

When it happens

Trigger: Calling listUsersForCaller with team_id set, caller is an authenticated active team member with role !== 'admin', and input.user_ids is non-empty or input.username is set (filtersPresent true).

Common situations: A UI autocomplete trying to resolve usernames within the team using a regular member token; code copied from an admin flow reused with member credentials; a version change where filters were previously tolerated for members.

Understand the failure class

Background: "You do not have permission" / 403 Forbidden errors: authenticated but not allowed — causes and fixes across open-source libraries — this error's family across 31 libraries.

Related errors

• missing_team_id
• 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/edce11572e746987. Report an issue: GitHub.