{"record":{"id":"5eda20c7a7031e20","repo":"openclaw/openclaw","slug":"codex-app-server-did-not-report-an-initialized-run","errorCode":null,"errorMessage":"Codex app-server did not report an initialized runtime identity","messagePattern":"Codex app-server did not report an initialized runtime identity","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"extensions/codex/src/app-server/runtime-artifact.ts","lineNumber":835,"sourceCode":"/** Rechecks startup bytes and adds initialized handshake identity. */\nexport async function finalizeCodexAppServerRuntimeArtifact(params: {\n  before: CodexAppServerRuntimeArtifactCapture;\n  startOptions: CodexAppServerStartOptions;\n  spawnIdentity: CodexRuntimeArtifactSpawnIdentity;\n  runtimeIdentity: CodexAppServerRuntimeIdentity | undefined;\n  signal?: AbortSignal;\n}): Promise<AgentHarnessRuntimeArtifactBinding> {\n  const afterDescriptor = await captureFilesystemDescriptor(params);\n  const afterContentFingerprint = await hashSelectedArtifactFiles(afterDescriptor, params.signal);\n  if (\n    JSON.stringify(afterDescriptor) !== JSON.stringify(params.before.descriptor) ||\n    afterContentFingerprint !== params.before.contentFingerprint\n  ) {\n    throw new Error(\"Codex app-server runtime artifact changed during startup\");\n  }\n  const serverVersion = params.runtimeIdentity?.serverVersion?.trim();\n  if (!serverVersion) {\n    throw new Error(\"Codex app-server did not report an initialized runtime identity\");\n  }\n  const userAgent = params.runtimeIdentity?.userAgent;\n  const descriptor: CodexRuntimeArtifactDescriptor = {\n    ...afterDescriptor,\n    serverVersion,\n    ...(userAgent\n      ? { userAgentFingerprint: createHash(\"sha256\").update(userAgent).digest(\"hex\") }\n      : {}),\n  };\n  validateArtifactDescriptorShape(descriptor);\n  const binding = Object.freeze({\n    id: encodeArtifactId(descriptor),\n    fingerprint: fingerprintBinding(descriptor, afterContentFingerprint),\n  });\n  return binding;\n}\n\n/** Checks current pre-spawn bytes and selection against a previously minted binding. */","sourceCodeStart":817,"sourceCodeEnd":853,"githubUrl":"https://github.com/openclaw/openclaw/blob/01804a75319da4b69c9ab98ceaa30477e22b8c0b/extensions/codex/src/app-server/runtime-artifact.ts#L817-L853","documentation":"Thrown by finalizeCodexAppServerRuntimeArtifact when the initialized app-server handshake did not supply a usable serverVersion (params.runtimeIdentity?.serverVersion?.trim() is empty). Without a serverVersion the artifact ID cannot be minted, so finalization fails fast rather than binding an incomplete identity.","triggerScenarios":"runtimeIdentity is undefined, or its serverVersion field is missing/empty/whitespace-only; line 833-835 throws.","commonSituations":"The Codex app-server crashed or hung before sending the initialized handshake; an incompatible/older harness omits serverVersion; a proxy or mock app-server did not implement the handshake fully; auth setup completed but the version announcement was dropped.","solutions":["Upgrade/reinstall the Codex harness so its initialized handshake includes serverVersion.","Verify the app-server process actually reached the initialized state (check logs/stderr).","If using a custom/mock app-server, emit a serverVersion string in the initialized notification.","Run openclaw doctor to detect a broken codex install."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"function hasRuntimeVersion(identity: unknown): identity is { serverVersion: string } {\n  return typeof (identity as any)?.serverVersion === \"string\" && (identity as any).serverVersion.trim().length > 0;\n}\nif (!hasRuntimeVersion(runtimeIdentity)) {\n  // do not attempt finalize; report app-server handshake failure\n}","typeGuard":"function hasServerVersion(identity: unknown): identity is { serverVersion: string; userAgent?: string } {\n  return typeof (identity as any)?.serverVersion === \"string\" && (identity as any).serverVersion.trim().length > 0;\n}","tryCatchPattern":null,"preventionTips":["Ensure the Codex harness version you run actually emits serverVersion in the initialized notification.","Verify the app-server process reached initialized (check stderr/logs) before finalizing.","Upgrade or reinstall the harness if the handshake is incomplete."],"tags":["codex","runtime-artifact","handshake","version","startup","app-server"],"backgroundTag":null,"analyzedSha":"01804a75319da4b69c9ab98ceaa30477e22b8c0b","analyzedAt":"2026-08-12T04:37:58.197Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}