jackwener/OpenCLI · error · CommandExecutionError

Could not launch ${label}: no compatible executable found in

Error message

Could not launch ${label}: no compatible executable found in ${path.join(appPath, 'Contents', 'MacOS')}

What it means

launchElectronApp scans <appPath>/Contents/MacOS for candidate executables and tried each one; when more than one candidate exists but every attempt failed (executables.length > 1 with a stored lastMissingExecutableError path) it throws this CommandExecutionError listing what it tried. It means the Electron app bundle could not be launched from the resolved path.

Source

Thrown at src/launcher.ts:317

  const executables = resolveExecutableCandidates(appPath, app);
  let lastMissingExecutableError: CommandExecutionError | undefined;

  for (const executable of executables) {
    log.debug(`[launcher] Launching: ${executable} ${args.join(' ')}`);
    try {
      await launchDetachedApp(executable, args, label);
      return;
    } catch (err) {
      if (isMissingExecutableError(err, label)) {
        lastMissingExecutableError = err as CommandExecutionError;
        continue;
      }
      throw err;
    }
  }

  if (executables.length > 1) {
    throw new CommandExecutionError(
      `Could not launch ${label}: no compatible executable found in ${path.join(appPath, 'Contents', 'MacOS')}`,
      `Tried: ${executables.map((executable) => path.basename(executable)).join(', ')}. Install ${label}, reinstall it, or register a custom app path in ~/.opencli/apps.yaml`,
    );
  }

  throw lastMissingExecutableError ?? new CommandExecutionError(
    `Could not launch ${label}`,
    `Install ${label}, reinstall it, or register a custom app path in ~/.opencli/apps.yaml`,
  );
}

export function electronLaunchArgs(port: number, extraArgs: string[] = []): string[] {
  return [
    `--remote-debugging-port=${port}`,
    '--remote-allow-origins=*',
    ...extraArgs,
  ];
}

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Reinstall the app so the bundle contains one working main executable.
  2. Set a custom app path in ~/.opencli/apps.yaml pointing to the correct .app bundle.
  3. Check the 'Tried:' list in the error and remove stale/duplicate binaries from Contents/MacOS, keeping only the main executable.
  4. Verify the binary matches your CPU architecture (arm64 vs x64).

Example fix

// before (~/.opencli/apps.yaml)
myapp: /Users/me/Downloads/MyApp-old.app
// after
myapp: /Applications/MyApp.app
Defensive patterns

Strategy: try-catch

Validate before calling

import fs from "fs";
const macosDir = path.join(appPath, "Contents", "MacOS");
if (!fs.existsSync(macosDir)) throw new Error(`Not a macOS app bundle: ${appPath}`);
const execs = fs.readdirSync(macosDir);
if (execs.length === 0) throw new Error(`No executables in ${macosDir}`);

Type guard

function isValidAppBundle(appPath: string): boolean {
  return fs.existsSync(path.join(appPath, "Contents", "MacOS"));
}

Try / catch

try {
  launchElectronApp(appPath);
} catch (e) {
  if (e instanceof CommandExecutionError && /no compatible executable/.test(e.message)) {
    console.error(`${e.message}\n${e.hint ?? ""} — reinstall the app or fix apps.yaml path`);
  }
}

Prevention

When it happens

Trigger: On macOS, resolveElectronEndpoint -> launchElectronApp with an appPath whose Contents/MacOS contains multiple files/executables (or multiple stale binaries) and none could be launched successfully.

Common situations: Corrupted or partial Electron install; custom app path in ~/.opencli/apps.yaml pointing at a bundle with helper binaries alongside the main one; app updated/renamed so old binaries remain; wrong architecture binary (x64 app on arm64).

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/11403c517afa33bf. Report an issue: GitHub.