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

[explore] ${reason}

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]`.

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)

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.

Related errors

• editor exited with status ${result.status ?? 'unknown'}
• ${EXPLORE_DEPRECATION_MESSAGE}\n\n${EXPLORE_HELP}
• stderr || `git ${args.join(' ')} failed`
• Unknown adapt argument: ${arg}
• Unknown adapt target: ${target}. Supported targets: ${suppor

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