can1357/oh-my-pi · error · RpcError

RPC message pagination returned an inconsistent total

Error message

RPC message pagination returned an inconsistent total

What it means

When collecting all messages, the client pages through get_messages_page() and remembers the first page's total_messages. If a later page reports a different total, the client raises this RpcError because the pages are no longer from one consistent snapshot — appending them would yield a corrupt transcript.

Source

Thrown at python/omp-rpc/src/omp_rpc/client.py:1035

        return parse_todo_phases(payload.get("todoPhases"))

    def clear_todos(self) -> tuple[TodoPhase, ...]:
        return self.set_todos(())

    def get_messages(self) -> tuple[AgentMessage, ...]:
        if self._protocol_version == 2:
            try:
                messages: list[AgentMessage] = []
                seen_cursors: set[str] = set()
                total_messages: int | None = None
                cursor: str | None = None
                while True:
                    page = self.get_messages_page(cursor=cursor, limit=256)
                    if (
                        total_messages is not None
                        and page.total_messages != total_messages
                    ):
                        raise RpcError(
                            "RPC message pagination returned an inconsistent total"
                        )
                    total_messages = page.total_messages
                    messages.extend(page.messages)
                    cursor = page.next_cursor
                    if cursor is None:
                        break
                    if cursor in seen_cursors:
                        raise RpcError("RPC message pagination repeated a cursor")
                    seen_cursors.add(cursor)
                if len(messages) != total_messages:
                    raise RpcError(
                        "RPC message pagination ended before the advertised total"
                    )
                return tuple(messages)
            except RpcCommandError as error:
                if error.command != "get_messages_page" or not (
                    error.code in _RPC_MESSAGES_PAGE_FALLBACK_CODES

View on GitHub (pinned to 9690622007)

Solutions

Re-run the full pagination from cursor=None once the session is idle/paused
Read the transcript from a finished session, or snapshot it server-side before paging
Upgrade server/client so pagination is served from a stable snapshot
Catch RpcError here and retry the whole pagination loop on transient inconsistency

Example fix

# before: paginating a live, still-growing session
messages = client.get_all_messages()  # total changed mid-loop -> RpcError

# after: retry after the run settles
for _ in range(3):
    try:
        messages = client.get_all_messages()
        break
    except RpcError:
        time.sleep(1)  # session still mutating; retry from scratch

Defensive patterns

Strategy: retry

Validate before calling

# page only when the session is not actively producing messages
state = client.get_state()
if getattr(state, "active", False):
    raise RuntimeError("session busy; wait for the run to finish before paginating")

Try / catch

for attempt in range(3):
    try:
        messages = client.get_all_messages()
        break
    except RpcError as e:
        if "inconsistent total" in str(e) and attempt < 2:
            time.sleep(1)
            continue
        raise

Prevention

Paginate only after the agent run reaches an idle/finished state
Retry the entire pagination loop on inconsistency (pages are re-read from scratch)
Avoid concurrent clients appending to the same session while paginating
Prefer a server version that snapshots totals per pagination run

When it happens

Trigger: Calling the client's get-all-messages path (loop around get_messages_page(cursor, limit=256)) while the server-side session is concurrently appending, trimming, or compacting messages so page.total_messages changes between requests.

Common situations: Reading a live agent session's history while it is actively generating messages; server-side compaction/pruning running mid-pagination; resuming a session in another client that adds messages between page fetches.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/cc9b3a0a0e1dade7. Report an issue: GitHub.