langchain-ai/deepagents · warning · ValueError

Invalid sort_by {sort_by!r}; expected 'updated' or 'created'

Error message

Invalid sort_by {sort_by!r}; expected 'updated' or 'created'

What it means

ValueError raised by list_threads when the sort_by argument is not exactly "updated" or "created". The SQL ordering column is chosen from this whitelist to prevent injection and keep the index-only scan valid.

Source

Thrown at libs/code/deepagents_code/sessions.py:479

        List of `ThreadInfo` dicts with `thread_id`, `agent_name`,
            `updated_at`, `created_at`, `latest_checkpoint_id`, `git_branch`,
            `cwd`, and optionally `message_count`.

    Raises:
        ValueError: If `sort_by` is not `"updated"` or `"created"`.
    """
    async with _connect() as conn:
        if not await _table_exists(conn, "checkpoints"):
            return []

        # Ensure the covering index exists before the GROUP BY below, so the
        # query is an index-only scan instead of a full scan over the (large,
        # blob-bearing) checkpoints table.
        await _ensure_threads_list_index(conn)

        if sort_by not in {"updated", "created"}:
            msg = f"Invalid sort_by {sort_by!r}; expected 'updated' or 'created'"
            raise ValueError(msg)
        order_col = "created_at" if sort_by == "created" else "updated_at"

        where_clauses: list[str] = []
        params_list: list[str | int] = []

        if agent_name:
            where_clauses.append("json_extract(metadata, '$.agent_name') = ?")
            params_list.append(agent_name)
        if branch:
            where_clauses.append("json_extract(metadata, '$.git_branch') = ?")
            params_list.append(branch)
        if cwd:
            where_clauses.append("json_extract(metadata, '$.cwd') = ?")
            params_list.append(cwd)

        where_sql = f"WHERE {' AND '.join(where_clauses)}" if where_clauses else ""

        query = f"""

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass only "updated" (default) or "created"
2. Normalize/validate user input before forwarding: sort_by = raw if raw in {"updated","created"} else "updated"
3. Lowercase and strip the input first if it comes from a CLI flag

Example fix

// before
threads = await list_threads(sort_by="Created")

// after
threads = await list_threads(sort_by="created")

VALID_SORTS = {"updated", "created"}
if sort_by not in VALID_SORTS:
    sort_by = "updated"

try:
    threads = await list_threads(sort_by=sort_by)
except ValueError:
    threads = await list_threads(sort_by="updated")

When it happens

Trigger: Calling list_threads(sort_by=...) with any other value (e.g. "name", "date", None, uppercase "Updated") via list_threads_command, _load_threads, or prewarm_thread_message_counts.

Common situations: Passing a user-supplied sort option straight through from a UI/config; typos; case-sensitivity mistakes; assuming other sort keys are supported.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• modes can only be provided when agent is a factory
• models can only be provided when agent is a factory
• -32602
• Could not parse embedded resource block. Block expected eith
• question text must not be blank

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/977b72871efcfcad. Report an issue: GitHub.