What causes "{field} accepts at most {max_items} items, got {len(deduped)}" in TencentCloud/TencentDB-Agent-Memory?

Chunk the list into batches within the cap (5000 or 100) and call the API per chunk

TencentCloud/TencentDB-Agent-Memory · error · ParamError

accepts at most items, got

Error message

{field} accepts at most {max_items} items, got {len(deduped)}

What it means

After stripping whitespace and deduplicating, _normalize_delete_ids enforces the server batch-size cap (5000 for message/atomic ids, 100 for session_ids/memory_ids). Exceeding it raises ParamError before any network call, protecting the caller from a server-side batch rejection.

Solutions

Chunk the list into batches within the cap (5000 or 100) and call the API per chunk
Deduplicate and strip first so near-cap lists may drop under the limit
For clear_chat_memory, prioritize the 100 most important memory_ids per call
Check len(set(s.strip() for s in ids)) before calling

Example fix

// before
client.delete_atomic(ids=all_ids)  # all_ids has 8000 entries
// after
for chunk in [all_ids[i:i+5000] for i in range(0, len(all_ids), 5000)]:
    client.delete_atomic(ids=chunk)

Defensive patterns

Strategy: validation

Validate before calling

MAX = 5000
unique = {s.strip() for s in ids if isinstance(s, str) and s.strip()}
if len(unique) > MAX:
    raise ValueError(f"{len(unique)} ids exceeds {MAX}")

Try / catch

try:
    client.delete_atomic(ids=ids)
except ParamError as e:
    if "accepts at most" in str(e):
        for chunk in batched(ids, 5000):
            client.delete_atomic(ids=chunk)

Prevention

Chunk all bulk operations at 5000 (or 100 for session/memory ids) by default
Deduplicate before batching to reduce batch count
Write a batched() utility and use it for every delete call
Log list lengths before large deletes

When it happens

Trigger: delete_conversation with >5000 deduped message_ids or >100 session_ids; delete_atomic with >5000 ids; clear_chat_memory with >100 memory_ids. Duplicates are removed first, so only unique stripped values count.

Common situations: Bulk cleanup scripts iterating an entire conversation history at once; migrating data between environments with unbounded id lists; replaying a queue of deletion jobs into a single call instead of batching.

Related errors

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

Appendix: source

Thrown at sdk/memory-core/python/tencentdb_agent_memory/v3/client.py:77

    破坏性操作的入参在客户端就拦一道，比等服务端回 400 更早暴露问题，
    也避免把明显不合法的批量请求发出去。

    :returns: 归一化后的列表；``raw`` 为 None 时返回 None（表示"未提供"）。
    """
    if raw is None:
        return None
    if not isinstance(raw, (list, tuple)):
        raise ParamError(f"{field} must be a list of non-empty strings")
    if any(not isinstance(item, str) or not item.strip() for item in raw):
        raise ParamError(f"{field} must contain only non-empty strings")

    seen: Dict[str, None] = {}
    for item in raw:
        seen.setdefault(item.strip(), None)
    deduped = list(seen.keys())

    if len(deduped) > max_items:
        raise ParamError(f"{field} accepts at most {max_items} items, got {len(deduped)}")
    return deduped


def _validate_construction(team_id: str, agent_id: str, user_id: str) -> None:
    """v3 构造时 team+agent+user 必填，任一缺失立刻 ParamError，避免 422 才暴露。

    session_id 不在构造时强校验（L2/L3 接口不需要）；L0/L1 方法调用时再单独校验。
    """
    missing = [
        name for name, val in (
            ("team_id", team_id),
            ("agent_id", agent_id),
            ("user_id", user_id),
        ) if not val
    ]
    if missing:
        raise ParamError(
            f"v3 MemoryClient requires non-empty {', '.join(missing)} at construction time"

View on GitHub (pinned to 3efcd317b8)