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

# Troubleshooting

> Common issues and their solutions.

Each section below shows the error text the server prints and the fix that resolves it.

## Server unreachable

```text theme={null}
Could not reach ai-cmo.dev at http://127.0.0.1:3000. Start the local ai-cmo.dev
app (from apps/web, run npm run dev), or set AICMO_BASE_URL to the running
app, then retry.
```

**Fix:** Ensure the ai-cmo.dev web app is running. If it runs on a different URL, set `AICMO_BASE_URL` to match.

> The legacy env var name `NOISEMAKER_BASE_URL` is still recognized as a fallback.

***

## Unauthorized (401)

```text theme={null}
ai-cmo.dev authorization is invalid or expired. Remove
~/.ai-cmo/credentials.json and retry to re-authorize.
```

**Fix:** The stored credential is no longer valid. Delete the credentials file and retry the tool to start a fresh device authorization flow:

```sh theme={null}
rm ~/.ai-cmo/credentials.json
```

Alternatively, set `AICMO_API_KEY` to a valid key.

> The legacy env var name `NOISEMAKER_API_KEY` is still recognized as a fallback.

***

## Workspace required

```text theme={null}
Choose a workspace slug for this tool call.
```

**Fix:** The credential can access multiple workspaces but no default was specified. Pass an explicit `workspace` parameter to the tool, or set a workspace when creating the credential.

If the credential has no accessible workspaces:

```text theme={null}
This credential cannot access an ai-cmo.dev workspace.
```

***

## Authorization expired

```text theme={null}
ai-cmo.dev authorization expired or was already claimed. Retry the tool to
authorize again.
```

**Fix:** The device authorization timed out after 10 minutes or was already claimed. Retry the tool to start a new authorization flow.

***

## Authorization denied

```text theme={null}
ai-cmo.dev authorization was denied.
```

**Fix:** You (or another user) denied the request in the browser. Retry the tool to start a new authorization.

***

## Stdio handshake smoke test

To verify the MCP server initializes correctly without contacting the web app:

```sh theme={null}
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}\n' \
  | AICMO_API_KEY=dummy node apps/mcp/dist/index.js \
  | head -1
```

A successful response contains a `"result"` field with `"serverCapabilities"`.

***

## Generic API error

```text theme={null}
ai-cmo.dev request failed with HTTP 4xx/5xx.
```

**Fix:** Check the ai-cmo.dev app logs and verify the API key has the required scopes.