{"record":{"id":"766a20268f5c6291","repo":"openai/codex-plugin-cc","slug":"a-claude-session-source-path-is-required","errorCode":null,"errorMessage":"A Claude session source path is required.","messagePattern":"A Claude session source path is required\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugins/codex/scripts/lib/codex.mjs","lineNumber":1064,"sourceCode":"      threadId: turnState.threadId,\n      sourceThreadId,\n      turnId: turnState.turnId,\n      reviewText: turnState.reviewText,\n      reasoningSummary: turnState.reasoningSummary,\n      turn: turnState.finalTurn,\n      error: turnState.error,\n      stderr: cleanCodexStderr(client.stderr)\n    };\n  });\n}\n\nexport async function importExternalAgentSession(cwd, options = {}) {\n  const availability = getCodexAvailability(cwd);\n  if (!availability.available) {\n    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`.\");\n  }\n  if (!options.sourcePath) {\n    throw new Error(\"A Claude session source path is required.\");\n  }\n\n  return withDirectAppServer(cwd, async (client) => {\n    emitProgress(options.onProgress, \"Importing Claude session into Codex.\", \"transferring\");\n    try {\n      await requestExternalAgentSessionImport(client, externalAgentSessionMigration(options.sourcePath, cwd));\n    } catch (error) {\n      if (error?.rpcCode === -32601) {\n        throw new Error(\n          \"This Codex version does not support Claude session transfer. Update Codex with `npm install -g @openai/codex@latest`, then retry.\",\n          { cause: error }\n        );\n      }\n      throw error;\n    }\n    const threadId = importedThreadIdForSource(options.sourcePath);\n    if (!threadId) {\n      const stderr = cleanCodexStderr(client.stderr);","sourceCodeStart":1046,"sourceCodeEnd":1082,"githubUrl":"https://github.com/openai/codex-plugin-cc/blob/db52e28f4d9ded852ab3942cea316258ae4ef346/plugins/codex/scripts/lib/codex.mjs#L1046-L1082","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass a non-empty sourcePath: importExternalAgentSession(cwd, { sourcePath: resolvedPath }).","Run the path through resolveClaudeSessionPath first and use its return value as sourcePath.","Validate options.sourcePath is a truthy string before calling.","If sourcing from env, read CODEX_COMPANION_TRANSCRIPT_PATH and pass it through."],"exampleFix":"// before\nawait importExternalAgentSession(cwd, {}) // throws\n\n// after\nconst resolved = resolveClaudeSessionPath(cwd, { source: flagSource })\nawait importExternalAgentSession(cwd, { sourcePath: resolved })","handlingStrategy":"validation","validationCode":"function requireSourcePath(options) {\n  if (!options?.sourcePath || typeof options.sourcePath !== 'string') {\n    throw new Error('sourcePath is required for import');\n  }\n  return options.sourcePath;\n}","typeGuard":"function hasSourcePath(o) {\n  return o != null && typeof o.sourcePath === 'string' && o.sourcePath.length > 0;\n}","tryCatchPattern":"null","preventionTips":["Always derive sourcePath from resolveClaudeSessionPath before importing.","Type-check options.sourcePath as a non-empty string in the caller.","Fail fast in the command layer if --source is missing.","Unit-test the import path with a valid sourcePath."],"tags":["codex","claude-transfer","validation","user-input"],"backgroundTag":null,"analyzedSha":"db52e28f4d9ded852ab3942cea316258ae4ef346","analyzedAt":"2026-08-13T05:13:20.855Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}