What causes "CDP not reachable at ${manualEndpoint}" in jackwener/OpenCLI?

Launch the Electron app with --remote-debugging-port= matching the port in OPENCLI_CDP_ENDPOINT, then retry the command.

jackwener/OpenCLI · critical · CommandExecutionError

CDP not reachable at ${manualEndpoint}

Error message

CDP not reachable at ${manualEndpoint}

What it means

This CommandExecutionError is thrown by executeCommand for Electron targets when the environment variable OPENCLI_CDP_ENDPOINT is set: the library parses its port and probes the Chrome DevTools Protocol endpoint (probeCDP). If the probe fails, the manually configured endpoint is unreachable, so the command cannot attach and execution is aborted with guidance about --remote-debugging-port. It is a connectivity/configuration error, not an argument error.

Source

Thrown at src/execution.ts:256

    command: fullName(cmd),
    args: kwargs,
    startedAt: Date.now(),
  };
  await emitHook('onBeforeExecute', hookCtx);

  let result: unknown;
  try {
    if (siteSession !== null) {
      const electron = isElectronApp(cmd.site);
      let cdpEndpoint: string | undefined;

      if (electron) {
        // Electron apps: respect manual endpoint override, then try auto-detect
        const manualEndpoint = process.env.OPENCLI_CDP_ENDPOINT;
        if (manualEndpoint) {
          const port = Number(new URL(manualEndpoint).port);
          if (!await probeCDP(port)) {
            throw new CommandExecutionError(
              `CDP not reachable at ${manualEndpoint}`,
              'Check that the app is running with --remote-debugging-port and the endpoint is correct.',
            );
          }
          cdpEndpoint = manualEndpoint;
        } else {
          cdpEndpoint = await resolveElectronEndpoint(cmd.site);
        }
      }

      const BrowserFactory = getBrowserFactory(cmd.site);
      // Requirement vs preference: --profile / OPENCLI_PROFILE route strictly;
      // the config default is a soft preference the daemon arbitrates.
      const profileSelection = resolveProfileSelection(opts.profile);
      const profileRouting = profileRouteParams(profileSelection);
      const contextId = profileSelection?.contextId;
      const internal = cmd as InternalCliCommand;
      const session = resolveAdapterBrowserSession(cmd, siteSession);

View on GitHub (pinned to 49907e53dc)

Solutions

Launch the Electron app with --remote-debugging-port=<port> matching the port in OPENCLI_CDP_ENDPOINT, then retry the command.
Verify the endpoint with curl: `curl http://<host>:<port>/json/version` — if it doesn't return JSON, fix the URL/port in OPENCLI_CDP_ENDPOINT.
Confirm the app is actually running and the debug port wasn't taken (a busy port makes Chromium skip remote debugging); restart the app on a free port.
If you don't need a manual endpoint, unset OPENCLI_CDP_ENDPOINT so the library uses its CDP auto-detection path instead.

Example fix

// before
export OPENCLI_CDP_ENDPOINT=http://127.0.0.1:9223
$ mycli inspect   // CDP not reachable at http://127.0.0.1:9223 (app launched without debug port)

// after
$ electron . --remote-debugging-port=9223 &
export OPENCLI_CDP_ENDPOINT=http://127.0.0.1:9223
$ mycli inspect

Defensive patterns

Strategy: fallback

Validate before calling

async function assertCdpReachable(endpoint) {
  const port = Number(new URL(endpoint).port);
  try {
    const res = await fetch(`http://127.0.0.1:${port}/json/version`);
    if (!res.ok) throw new Error(`CDP returned ${res.status}`);
  } catch (e) {
    throw new Error(`CDP not reachable at ${endpoint}: ${e.message}`);
  }
}
// before running commands: if (process.env.OPENCLI_CDP_ENDPOINT) await assertCdpReachable(process.env.OPENCLI_CDP_ENDPOINT);

Try / catch

try {
  await executeCommand(cmd, kwargs);
} catch (err) {
  if (err instanceof CommandExecutionError && /CDP not reachable/.test(err.message)) {
    delete process.env.OPENCLI_CDP_ENDPOINT; // fall back to CDP auto-detection
    await executeCommand(cmd, kwargs);
  } else {
    throw err;
  }
}

Prevention

Always launch the Electron app with --remote-debugging-port matching OPENCLI_CDP_ENDPOINT.
Curl http://127.0.0.1:<port>/json/version to verify the endpoint before running commands.
Ensure the configured port is free at app startup; a busy port disables remote debugging.
In containers/VMs, point the endpoint at an address reachable from the CLI process, not just the app's localhost.

When it happens

Trigger: OPENCLI_CDP_ENDPOINT is set to an endpoint whose host:port does not answer CDP — the Electron app was not launched with --remote-debugging-port=<port>, the app isn't running yet, a wrong port/host is configured, or a firewall blocks the connection so probeCDP(port) returns false.

Common situations: Forgetting to pass --remote-debugging-port when launching the Electron app; stale OPENCLI_CDP_ENDPOINT pointing at a previous run's port; the app crashed or restarted on a different debug port; running inside a container/VM where localhost doesn't reach the app; port already occupied so the app's debugger never started.

Related errors

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