openai/codex-plugin-cc · error · Error

A Claude session source path is required.

Error message

A Claude session source path is required.

What it means

Thrown by importExternalAgentSession when options.sourcePath is falsy. After the Codex availability check passes, the function requires a concrete Claude transcript path to build the migration payload; an empty sourcePath means there is nothing to import.

Source

Thrown at plugins/codex/scripts/lib/codex.mjs:1064

      threadId: turnState.threadId,
      sourceThreadId,
      turnId: turnState.turnId,
      reviewText: turnState.reviewText,
      reasoningSummary: turnState.reasoningSummary,
      turn: turnState.finalTurn,
      error: turnState.error,
      stderr: cleanCodexStderr(client.stderr)
    };
  });
}

export async function importExternalAgentSession(cwd, options = {}) {
  const availability = getCodexAvailability(cwd);
  if (!availability.available) {
    throw new Error("Codex CLI is not installed or is missing required runtime support. Install it with `npm install -g @openai/codex`, then rerun `/codex:setup`.");
  }
  if (!options.sourcePath) {
    throw new Error("A Claude session source path is required.");
  }

  return withDirectAppServer(cwd, async (client) => {
    emitProgress(options.onProgress, "Importing Claude session into Codex.", "transferring");
    try {
      await requestExternalAgentSessionImport(client, externalAgentSessionMigration(options.sourcePath, cwd));
    } catch (error) {
      if (error?.rpcCode === -32601) {
        throw new Error(
          "This Codex version does not support Claude session transfer. Update Codex with `npm install -g @openai/codex@latest`, then retry.",
          { cause: error }
        );
      }
      throw error;
    }
    const threadId = importedThreadIdForSource(options.sourcePath);
    if (!threadId) {
      const stderr = cleanCodexStderr(client.stderr);

View on GitHub (pinned to db52e28f4d)

Solutions

1. Pass a non-empty sourcePath: importExternalAgentSession(cwd, { sourcePath: resolvedPath }).
2. Run the path through resolveClaudeSessionPath first and use its return value as sourcePath.
3. Validate options.sourcePath is a truthy string before calling.
4. If sourcing from env, read CODEX_COMPANION_TRANSCRIPT_PATH and pass it through.

Example fix

// before
await importExternalAgentSession(cwd, {}) // throws

// after
const resolved = resolveClaudeSessionPath(cwd, { source: flagSource })
await importExternalAgentSession(cwd, { sourcePath: resolved })

function requireSourcePath(options) {
  if (!options?.sourcePath || typeof options.sourcePath !== 'string') {
    throw new Error('sourcePath is required for import');
  }
  return options.sourcePath;
}

function hasSourcePath(o) {
  return o != null && typeof o.sourcePath === 'string' && o.sourcePath.length > 0;
}

null

When it happens

Trigger: Calling importExternalAgentSession(cwd, {}) or importExternalAgentSession(cwd, { sourcePath: '' }). The caller resolved the transcript via resolveClaudeSessionPath but passed an undefined result, or the --source flag was dropped before reaching this function.

Common situations: A wrapper omitted the sourcePath field. resolveClaudeSessionPath returned undefined/null due to upstream logic and that was forwarded. A slash-command parsing bug dropped the argument.

Related errors

• A prompt is required for this Codex run.
• Could not identify the current Claude transcript. Retry with
• Claude session source must be a JSONL file: ${sourcePath}
• This Codex version does not support Claude session transfer.
• Codex reported that the Claude import completed, but did not

AI-assisted analysis of openai/codex-plugin-cc@db52e28f4d (2026-08-13). Data as JSON: /api/errors/766a20268f5c6291. Report an issue: GitHub.