{"record":{"id":"f9b05fb48100e98a","repo":"Yeachan-Heo/oh-my-codex","slug":"explore-reason","errorCode":null,"errorMessage":"[explore] ${reason}","messagePattern":"\\[explore\\] (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/cli/explore.ts","lineNumber":56,"sourceCode":"  platform?: string;\n  arch?: string;\n}\n\nexport function getBuiltinExploreHarnessUnsupportedReason(\n  platform: NodeJS.Platform = process.platform,\n  env: NodeJS.ProcessEnv = process.env,\n): string | undefined {\n  if (platform !== 'win32') return undefined;\n  if (env[EXPLORE_BIN_ENV]?.trim()) return undefined;\n  return WINDOWS_BUILTIN_EXPLORE_HARNESS_REASON;\n}\n\nexport function assertBuiltinExploreHarnessSupported(\n  platform: NodeJS.Platform = process.platform,\n  env: NodeJS.ProcessEnv = process.env,\n): void {\n  const reason = getBuiltinExploreHarnessUnsupportedReason(platform, env);\n  if (reason) throw new Error(`[explore] ${reason}`);\n}\n\nexport function packagedExploreHarnessBinaryName(platform: NodeJS.Platform = process.platform): string {\n  return platform === 'win32' ? 'omx-explore-harness.exe' : 'omx-explore-harness';\n}\n\nexport function resolvePackagedExploreHarnessCommand(\n  packageRoot = getPackageRoot(),\n  platform: NodeJS.Platform = process.platform,\n  arch = process.arch,\n): ExploreHarnessCommand | undefined {\n  const metadataPath = join(packageRoot, 'bin', 'omx-explore-harness.meta.json');\n  if (!existsSync(metadataPath)) return undefined;\n  try {\n    const metadata = JSON.parse(readFileSync(metadataPath, 'utf-8')) as ExploreHarnessMetadata;\n    const expectedPlatform = metadata.platform?.trim();\n    const expectedArch = metadata.arch?.trim();\n    if (expectedPlatform && expectedPlatform !== platform) return undefined;","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/Yeachan-Heo/oh-my-codex/blob/3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2/src/cli/explore.ts#L38-L74","documentation":"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]`.","triggerScenarios":"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).","commonSituations":"Running the explore harness in CI containers, unusual OS/arch combos, or environments missing prerequisites the harness relies on.","solutions":["Read the `[explore] <reason>` message — it states the exact unsupported condition","Use the packaged harness binary instead via `packagedExploreHarnessBinaryName` (omx-explore-harness / .exe)","Run on a supported platform/environment per the reason text","Upgrade the tool if support for your platform was added later"],"exampleFix":"// before\nassertBuiltinExploreHarnessSupported();\n\n// after\nconst reason = getBuiltinExploreHarnessUnsupportedReason(process.platform, process.env);\nif (reason) {\n  // fall back to packaged harness binary\n  usePackagedHarness(packagedExploreHarnessBinaryName(process.platform));\n} else {\n  assertBuiltinExploreHarnessSupported();\n}","handlingStrategy":"type-guard","validationCode":"import { getBuiltinExploreHarnessUnsupportedReason } from './src/cli/explore';\nconst reason = getBuiltinExploreHarnessUnsupportedReason(process.platform, process.env);\nif (reason) console.log('Unsupported:', reason);","typeGuard":"function isExploreHarnessSupported(\n  platform: NodeJS.Platform = process.platform,\n  env: NodeJS.ProcessEnv = process.env,\n): boolean {\n  return getBuiltinExploreHarnessUnsupportedReason(platform, env) === undefined;\n}","tryCatchPattern":"try {\n  assertBuiltinExploreHarnessSupported();\n} catch (e) {\n  if ((e as Error).message.startsWith('[explore]')) {\n    // fall back to packaged harness binary\n  } else throw e;\n}","preventionTips":["Pre-check support with getBuiltinExploreHarnessUnsupportedReason before asserting","Have the packaged harness fallback ready on heterogeneous CI fleets"],"tags":["cli","platform-support","explore","environment"],"backgroundTag":"unsupported-platform","analyzedSha":"3ad79a8a6fe6e95fdbb8c00e40716fffe4011ce2","analyzedAt":"2026-08-27T22:18:39.783Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}