User guide

Troubleshoot common problems

Use these checks to diagnose common setup and workflow issues.

If you need help, you can create an anonymized support ticket from the app with /support [run-id]. For a failed run, the command includes run context in a prefilled GitHub issue.

The compiler is not configured

Open Settings -> Compiler and choose a backend. For automatic API-key selection, set ANTHROPIC_API_KEY or OPENAI_API_KEY before starting the app. Account-backed connections require the corresponding codex or claude CLI to be installed and signed in.

The MCP server cannot bind its port

The default endpoint is http://127.0.0.1:39387/mcp. If the configured port cannot be bound, the server tries an available ephemeral port instead; check the reported listening port and update your client URL. To choose a different fixed port, change it under Settings -> Local MCP server, save, and restart. INXM_MCP_ONLY=1 inxm-local is useful when the native window cannot start.

A remote MCP tool needs authorization

Start authorization from MCP Tools -> Connect while the desktop app is available. Scheduled and headless runs cannot open an interactive OAuth flow. Reconnect if the credential expired or the server requested new scopes.

A schedule does not fire

Check that the schedule is enabled and that either the desktop app is allowed to keep running in the tray or inxm-local --headless is running. A second process using the same data directory will not start a duplicate scheduler.

A tool works in a terminal but fails in the app

For a missing executable, check the effective PATH and the resolved gh location in Settings. Add the absolute folder containing the executable under Extra executable folders, save, and fully quit and reopen INXM Local. See Extra executable folders. This does not install the program. An explicit tool PATH overrides the app's environment and may need its own correction.

When opened from the desktop, INXM Local does not pass tokens or API keys from your shell profile to tools. A tool that depends on one may work in your terminal but fail in the app. A GitHub MCP server, for example, fails to authenticate when GITHUB_TOKEN is set only in your shell profile. The same applies to a proxy variable whose URL contains a username or password, such as HTTPS_PROXY=http://user:password@proxy:8080. Started from a terminal, INXM Local passes on that terminal's full environment, including credentials. Add the variable to the tool's Env or Server env field, such as GITHUB_TOKEN=ghp_yourTokenHere, and try again. See Tool environment for what tools receive.

Edit this page