Yeachan-Heo/oh-my-codex · error · Error

[explore]

Error message

[explore] ${reason}

What it means

The built-in `explore` harness is not supported on the current platform/environment. `getBuiltinExploreHarnessUnsupportedReason` detected a blocking condition (e.g. unsupported OS/arch or missing required env), and this assert helper converts that reason into a thrown error prefixed with `[explore]`.

Solutions

1. Read the `[explore] <reason>` message — it states the exact unsupported condition
2. Use the packaged harness binary instead via `packagedExploreHarnessBinaryName` (omx-explore-harness / .exe)
3. Run on a supported platform/environment per the reason text
4. Upgrade the tool if support for your platform was added later

Example fix

// before
assertBuiltinExploreHarnessSupported();

// after
const reason = getBuiltinExploreHarnessUnsupportedReason(process.platform, process.env);
if (reason) {
  // fall back to packaged harness binary
  usePackagedHarness(packagedExploreHarnessBinaryName(process.platform));
} else {
  assertBuiltinExploreHarnessSupported();
}

import { getBuiltinExploreHarnessUnsupportedReason } from './src/cli/explore';
const reason = getBuiltinExploreHarnessUnsupportedReason(process.platform, process.env);
if (reason) console.log('Unsupported:', reason);

function isExploreHarnessSupported(
  platform: NodeJS.Platform = process.platform,
  env: NodeJS.ProcessEnv = process.env,
): boolean {
  return getBuiltinExploreHarnessUnsupportedReason(platform, env) === undefined;
}

try {
  assertBuiltinExploreHarnessSupported();
} catch (e) {
  if ((e as Error).message.startsWith('[explore]')) {
    // fall back to packaged harness binary
  } else throw e;
}

When it happens

Trigger: Calling `assertBuiltinExploreHarnessSupported()` (directly or via explore setup code) on an unsupported Node platform or with an environment that fails the harness's requirements (e.g. Windows variants or restricted env vars depending on the check).

Common situations: Running the explore harness in CI containers, unusual OS/arch combos, or environments missing prerequisites the harness relies on.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• editor exited with status
• \n\n
• agent already exists
• agent name must not be empty
• agent not found

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/f9b05fb48100e98a. Report an issue: GitHub.

Appendix: source

Thrown at src/cli/explore.ts:56

  platform?: string;
  arch?: string;
}

export function getBuiltinExploreHarnessUnsupportedReason(
  platform: NodeJS.Platform = process.platform,
  env: NodeJS.ProcessEnv = process.env,
): string | undefined {
  if (platform !== 'win32') return undefined;
  if (env[EXPLORE_BIN_ENV]?.trim()) return undefined;
  return WINDOWS_BUILTIN_EXPLORE_HARNESS_REASON;
}

export function assertBuiltinExploreHarnessSupported(
  platform: NodeJS.Platform = process.platform,
  env: NodeJS.ProcessEnv = process.env,
): void {
  const reason = getBuiltinExploreHarnessUnsupportedReason(platform, env);
  if (reason) throw new Error(`[explore] ${reason}`);
}

export function packagedExploreHarnessBinaryName(platform: NodeJS.Platform = process.platform): string {
  return platform === 'win32' ? 'omx-explore-harness.exe' : 'omx-explore-harness';
}

export function resolvePackagedExploreHarnessCommand(
  packageRoot = getPackageRoot(),
  platform: NodeJS.Platform = process.platform,
  arch = process.arch,
): ExploreHarnessCommand | undefined {
  const metadataPath = join(packageRoot, 'bin', 'omx-explore-harness.meta.json');
  if (!existsSync(metadataPath)) return undefined;
  try {
    const metadata = JSON.parse(readFileSync(metadataPath, 'utf-8')) as ExploreHarnessMetadata;
    const expectedPlatform = metadata.platform?.trim();
    const expectedArch = metadata.arch?.trim();
    if (expectedPlatform && expectedPlatform !== platform) return undefined;

View on GitHub (pinned to 3ad79a8a6f)