jackwener/OpenCLI · error · CommandExecutionError

Codex sidebar project extraction returned an invalid payload

Error message

Codex sidebar project extraction returned an invalid payload

What it means

`readCodexProjects` runs `collectCodexProjectsFromDocument` inside the Codex page and expects an array back. If the in-page evaluation returns anything other than an array (null, undefined, object, or an error proxy), the payload is considered corrupted and this `CommandExecutionError` is thrown rather than propagating malformed data.

Source

Thrown at clis/codex/sidebar.js:298

        for (const conversation of conversations) {
            rows.push({
                Project: project.project,
                Index: conversation.index,
                Title: conversation.title,
                Updated: conversation.updated,
                Active: conversation.active ? 'yes' : '',
                ProjectPath: project.projectPath,
                ThreadId: conversation.threadId,
            });
        }
    }
    return rows;
}

export async function readCodexProjects(page) {
    const projects = await page.evaluate(`(${collectCodexProjectsFromDocument.toString()})()`);
    if (!Array.isArray(projects)) {
        throw new CommandExecutionError('Codex sidebar project extraction returned an invalid payload');
    }
    return projects;
}

export async function openCodexConversation(page, kwargs) {
    if (!hasConversationTarget(kwargs))
        return null;
    const index = parseOptionalPositiveIntegerOption(kwargs.index, 'codex conversation --index');
    const threadId = kwargs['thread-id'] ? requireNonEmptyOption(kwargs['thread-id'], 'codex conversation --thread-id') : '';
    const target = {
        project: kwargs.project || '',
        conversation: kwargs.conversation || '',
        index: index == null ? '' : String(index),
        threadId,
        preferNativeClick: typeof page.nativeClick === 'function',
    };
    let result = await page.evaluate(`(${selectCodexConversationInDocument.toString()})(${JSON.stringify(target)})`);
    if (result?.expanded) {

View on GitHub (pinned to 49907e53dc)

Solutions

Ensure the browser page is on the Codex app and fully loaded before running the sidebar command.
Re-run the command; transient navigation races usually resolve.
Reload the Codex page to restore a stable document, then retry.
If it persists after a Codex UI update, the collection script may need updating to the new DOM.

Defensive patterns

Strategy: type-guard

Validate before calling

// Before reading projects, confirm the page is the Codex app
const onCodexApp = await page.evaluate(`location.hostname.includes('codex') && !!document.querySelector('[data-app-action-sidebar-project-row]')`);
if (!onCodexApp) throw new Error('Browser is not on a loaded Codex app page');

Type guard

const isProjectArray = (v) => Array.isArray(v);

Try / catch

try {
  const projects = await readCodexProjects(page);
} catch (e) {
  if (String(e.message).includes('invalid payload')) {
    await page.reload({ waitUntil: 'networkidle' });
    const projects = await readCodexProjects(page);
  } else throw e;
}

Prevention

Ensure the automation page is on the Codex app and fully loaded before sidebar calls.
Avoid sidebar reads during SPA navigation/reload.
Recover by reloading the page and retrying once.
After Codex UI updates, verify the DOM selectors still resolve.

When it happens

Trigger: `page.evaluate` of the collection script returns a non-array — the page context changed (not on the Codex app page), the script was interrupted by navigation, serialization of the result failed, or the injected function returned early with undefined due to unexpected DOM/exceptions swallowed upstream.

Common situations: Running the sidebar command while the browser is on a different tab/URL than the Codex app; Codex SPA mid-navigation so the document is being replaced; browser automation session expired or page crashed.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/f7aac2c0bcd6d93f. Report an issue: GitHub.