openclaw/openclaw · error · Error

Codex app-server did not report an initialized runtime ident

Error message

Codex app-server did not report an initialized runtime identity

What it means

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.

Source

Thrown at extensions/codex/src/app-server/runtime-artifact.ts:835

/** Rechecks startup bytes and adds initialized handshake identity. */
export async function finalizeCodexAppServerRuntimeArtifact(params: {
  before: CodexAppServerRuntimeArtifactCapture;
  startOptions: CodexAppServerStartOptions;
  spawnIdentity: CodexRuntimeArtifactSpawnIdentity;
  runtimeIdentity: CodexAppServerRuntimeIdentity | undefined;
  signal?: AbortSignal;
}): Promise<AgentHarnessRuntimeArtifactBinding> {
  const afterDescriptor = await captureFilesystemDescriptor(params);
  const afterContentFingerprint = await hashSelectedArtifactFiles(afterDescriptor, params.signal);
  if (
    JSON.stringify(afterDescriptor) !== JSON.stringify(params.before.descriptor) ||
    afterContentFingerprint !== params.before.contentFingerprint
  ) {
    throw new Error("Codex app-server runtime artifact changed during startup");
  }
  const serverVersion = params.runtimeIdentity?.serverVersion?.trim();
  if (!serverVersion) {
    throw new Error("Codex app-server did not report an initialized runtime identity");
  }
  const userAgent = params.runtimeIdentity?.userAgent;
  const descriptor: CodexRuntimeArtifactDescriptor = {
    ...afterDescriptor,
    serverVersion,
    ...(userAgent
      ? { userAgentFingerprint: createHash("sha256").update(userAgent).digest("hex") }
      : {}),
  };
  validateArtifactDescriptorShape(descriptor);
  const binding = Object.freeze({
    id: encodeArtifactId(descriptor),
    fingerprint: fingerprintBinding(descriptor, afterContentFingerprint),
  });
  return binding;
}

/** Checks current pre-spawn bytes and selection against a previously minted binding. */

View on GitHub (pinned to 01804a7531)

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.

Defensive patterns

Strategy: validation

Validate before calling

function hasRuntimeVersion(identity: unknown): identity is { serverVersion: string } {
  return typeof (identity as any)?.serverVersion === "string" && (identity as any).serverVersion.trim().length > 0;
}
if (!hasRuntimeVersion(runtimeIdentity)) {
  // do not attempt finalize; report app-server handshake failure
}

Type guard

function hasServerVersion(identity: unknown): identity is { serverVersion: string; userAgent?: string } {
  return typeof (identity as any)?.serverVersion === "string" && (identity as any).serverVersion.trim().length > 0;
}

Prevention

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.

When it happens

Trigger: runtimeIdentity is undefined, or its serverVersion field is missing/empty/whitespace-only; line 833-835 throws.

Common situations: 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.

Related errors

AI-assisted analysis of openclaw/openclaw@01804a7531 (2026-08-12). Data as JSON: /api/errors/5eda20c7a7031e20. Report an issue: GitHub.