> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for the most common CLI errors — missing binaries, auth failures, validation errors, and network problems.

## `command not found: userintuition-mcp`

The binary isn't on your `PATH`. Pick the install style you used and verify:

<Tabs>
  <Tab title="Global install">
    ```bash theme={null}
    npm install -g @userintuition-ai/mcp
    which userintuition-mcp     # should print a path
    ```

    If `which` is empty, your global `npm` bin directory isn't on `PATH`. Run `npm config get prefix` and add `<prefix>/bin` to `PATH`.
  </Tab>

  <Tab title="Project-local install">
    ```bash theme={null}
    npm install --save-dev @userintuition-ai/mcp
    npx userintuition-mcp list  # use `npx` — node_modules/.bin/ isn't on PATH by default
    ```
  </Tab>

  <Tab title="One-shot">
    ```bash theme={null}
    npx -y @userintuition-ai/mcp list
    ```

    No install needed — npm downloads on demand.
  </Tab>

  <Tab title="Local checkout (contributors)">
    A package's own `bin` does **not** appear in its own `node_modules/.bin/`. Use one of:

    ```bash theme={null}
    # Symlink globally
    cd userintuition-mcpserver-ts && npm link
    userintuition-mcp list

    # Or run dist directly
    node ./dist/index.js list

    # Or run source via tsx (no build step)
    npx tsx ./src/index.ts list
    ```
  </Tab>
</Tabs>

***

## `No authentication found`

```
{"error":"No authentication found. Set USERINTUITION_API_KEY environment variable …"}
```

The CLI couldn't read `USERINTUITION_API_KEY` from its environment. Common causes:

1. **Not exported in the current shell.**
   ```bash theme={null}
   export USERINTUITION_API_KEY=ui_sk_...
   userintuition-mcp call list_studies
   ```
2. **Set in `~/.zshrc` but the shell didn't reload.** Open a new terminal or `source ~/.zshrc`.
3. **Running under `sudo` or a different user.** `sudo` strips most env vars — prefix the call: `sudo USERINTUITION_API_KEY=ui_sk_... userintuition-mcp call …`
4. **CI secret not wired.** Confirm the variable is set as a secret in your CI provider *and* exposed to the step that runs the CLI.

***

## `401 Unauthorized` from the backend

The key is read but the backend rejected it.

* **Revoked or rotated.** Generate a new key at [app.userintuition.ai → Settings → API Keys](https://app.userintuition.ai) and update your environment.
* **Wrong environment.** Production keys (`ui_sk_live_...`) don't work against staging and vice versa. Check `BACKEND_URL` if you've overridden it.
* **Typo / wrapping whitespace.** `echo "$USERINTUITION_API_KEY" | wc -c` — should match expected key length (no trailing newline issues).

***

## `Invalid input for <tool>: …`

Zod schema validation failed *before* the CLI tried to call the backend. The error message names the offending field.

```bash theme={null}
$ userintuition-mcp call ask_humans --mode bogus --text x
Invalid input for ask_humans: Invalid enum value. Expected 'preference' | 'claim' | 'message', received 'bogus'
```

Re-read the schema:

```bash theme={null}
userintuition-mcp describe ask_humans
```

Common variants:

* **Missing required flag.** Add it.
* **String where a number/boolean/array is expected.** Make sure the value is JSON-parseable: `--n 25` not `--n "twenty-five"`; `--options '["A","B"]'` not `--options A,B`.
* **Nested objects.** Use `--input-json` rather than flags.

***

## Tool call hangs or times out

Network egress to `api.userintuition.ai` may be blocked or slow.

```bash theme={null}
curl -sS -w "%{http_code}\n" -o /dev/null https://api.userintuition.ai/health
# Expect 200
```

If the curl works but the CLI hangs, the tool may legitimately be long-running (e.g. `generate_powerpoint`). Check the equivalent operation in the dashboard — if it normally takes minutes, the CLI behaves the same way.

If you're on a corporate network, confirm a proxy hasn't TLS-intercepted the connection. Node respects `HTTPS_PROXY`; set it explicitly if needed.

***

## `EACCES` / permission denied on the binary

After a manual `tsc` build, `dist/index.js` may not be executable.

```bash theme={null}
chmod +x ./dist/index.js
```

`npm publish` handles this automatically — only a concern for local builds.

***

## Output isn't valid JSON

The CLI writes the tool's text response verbatim to stdout. Most tools return JSON; a few (e.g. PowerPoint generation) return a URL or status string. Use `userintuition-mcp describe <tool>` to confirm the response shape, and check whether the tool returned an `{"error": …}` envelope on a logical failure.

If stderr contents are being mixed into your pipe, redirect them out: `userintuition-mcp call … 2>/dev/null | jq .`.

***

## Still stuck?

Run the equivalent MCP call through the official inspector to isolate whether the issue is the CLI or the underlying tool:

```bash theme={null}
npx @modelcontextprotocol/inspector npx -y @userintuition-ai/mcp
```

If it reproduces there, the bug is in the tool or the backend — open an issue at [github.com/userintuition](https://github.com/userintuition). If it only reproduces in the CLI, please include the exact command, your CLI version (`npm ls -g @userintuition-ai/mcp`), and Node version (`node --version`).