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

# Troubleshooting

> Common issues and solutions for CodeArchitect MCP

## Sessions saved in wrong location

**Note:** Sessions are always saved to `~/.codearchitect/sessions/` (home directory). This is intentional and ensures reliable storage across all projects.

**If you want to also save to project folder:**

* Use `projectDir` parameter: `use codearchitect store_session projectDir: "/path/to/project"`
* This saves to both main folder (`~/.codearchitect/sessions/`) AND project folder (`project/.codearchitect/sessions/`)

**Main location:**

* Windows: `C:\Users\YourName\.codearchitect\sessions\`
* Linux/Mac: `~/.codearchitect/sessions/`

## Session files not being created

**Check:**

* Write permissions: `chmod -R u+w ~/.codearchitect/` (Linux/Mac)
* MCP server logs in IDE Output panel
* Main location exists: `~/.codearchitect/sessions/` (created automatically)
* Export folder exists: `~/.codearchitect/exports/` (for auto-detection)

## MCP server not starting

**Verify:**

```bash theme={null}
npx -y codearchitect-mcp@latest  # Should run without errors
node --version                    # Should be v18+
```

**If using global install:**

```bash theme={null}
codearchitect-mcp --version  # Should show version
npm install -g codearchitect-mcp  # Reinstall if missing
```

**Recommended:** Use `npx` method (no global install needed):

```json theme={null}
{
  "mcpServers": {
    "codearchitect": {
      "command": "npx",
      "args": ["-y", "codearchitect-mcp@latest"]
    }
  }
}
```

## Topic extraction issues

Provide explicit `topic` parameter. Topics are limited to 50 characters.

## Permission errors

**Linux/Mac:** `chmod -R u+w ~/.codearchitect/`\
**Windows:** Check folder Properties → Security → Write permissions for `C:\Users\YourName\.codearchitect\`

## Getting Help

* [GitHub Issues](https://github.com/tairqaldy/codearchitect-mcp/issues)
* [Telegram](https://t.me/tairqaldy)

Include: description, steps to reproduce, environment (OS, Node version, IDE), and MCP server logs.