# Common Errors When Using DeusData codebase-memory-mcp: Installation, Configuration, and Daemon Issues Explained

> Troubleshoot common DeusData codebase-memory-mcp errors including macOS quarantine, PowerShell policies, and daemon conflicts. Resolve installation and configuration issues with our guide.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-25

---

**Most common errors in DeusData codebase-memory-mcp stem from macOS quarantine restrictions, PowerShell execution policies, daemon version conflicts, and port binding issues, all of which can be resolved with specific permission changes and configuration adjustments.**

`codebase-memory-mcp` is a high-performance, single-binary code-intelligence engine maintained by DeusData. While the tool is designed for seamless integration with coding agents, users frequently encounter roadblocks during the initial installation phase, daemon coordination, or environment configuration. Understanding these failure modes—documented explicitly in the repository's [`README.md`](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md) and installer scripts—ensures you can diagnose and resolve issues without debugging the underlying C source directly.

## Installation Script Failures

The first interaction most users have with the repository involves the automated installation scripts. These scripts handle binary placement, permission stripping, and agent configuration, but platform-specific security controls often interrupt the process.

### macOS Quarantine and Missing Execute Permissions

macOS adds a **quarantine attribute** to downloaded files, preventing [`install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh) from running even after download. According to line [100](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L100) of the documentation, the script attempts to strip this attribute automatically, but older macOS versions may still block execution. Additionally, the script may lack execute permissions upon download.

Run the following commands to resolve both issues:

```bash
chmod +x install.sh
xattr -d com.apple.quarantine ./install.sh
./install.sh

```

### Windows PowerShell Execution Policy Errors

PowerShell's default execution policy blocks unsigned scripts, causing `install.ps1` to fail immediately. The README warns about this restriction at lines [70-71](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L70).

Temporarily bypass the policy for the current session:

```bash
Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1

```

Alternatively, launch the installer with explicit policy bypass:

```bash
PowerShell -ExecutionPolicy Bypass -File .\install.ps1

```

## Daemon Coordination and Runtime Conflicts

Once installed, `codebase-memory-mcp` relies on a coordination daemon that enforces strict consistency across all running processes. Mismatches in this layer produce immediate failures.

### Duplicate Daemon and Version Mismatch

The coordination daemon requires that **all running processes share the same binary build and cache root**. If a different version is launched, the daemon aborts with a conflict message, as noted at lines [119-120](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L119).

Resolve this by updating all sessions to the same version and terminating stray processes:

```bash
codebase-memory-mcp update
pkill codebase-memory-mcp
codebase-memory-mcp install

```

The update command is documented at lines [158-161](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L158).

### UI Port Already in Use

The UI component binds to **port 9749** by default. If another process holds that port, the UI fails to start silently or with a binding error. Lines [138-141](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L138) describe the UI launch parameters.

Check for port conflicts:

```bash

# Linux/macOS

lsof -i :9749

# Windows

netstat -ano | findstr 9749

```

Launch the UI on an alternative port:

```bash
codebase-memory-mcp --ui=true --port=9750

```

## Configuration and Environment Issues

Beyond installation and runtime conflicts, several environment-specific misconfigurations can prevent the daemon from starting or indexing correctly.

### Auto-Index Limits and Watcher Registration

By default, the daemon watches every new project through the file-watcher implemented in [`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c). In environments with massive repository counts, the watcher hits internal file limits, causing indexing to stop silently. Lines [145-152](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L145) document these configurable limits.

Reduce the auto-index limit or disable automatic watching:

```bash
codebase-memory-mcp config set auto_index_limit 20000
codebase-memory-mcp config set auto_watch false

```

The `auto_watch` configuration is specifically mentioned at line [154](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L154).

### Missing CBM_CACHE_DIR Environment Variable

The daemon stores logs and index data under `${CBM_CACHE_DIR}`. If this variable is unset or points to a non-existent directory, the daemon refuses to start, often without a descriptive error message.

Set the variable and ensure the directory exists:

```bash
export CBM_CACHE_DIR=$HOME/.cache/codebase-memory-mcp
mkdir -p $CBM_CACHE_DIR

```

### Binary Variant Mismatch (Headless vs UI)

The repository ships two distinct binaries: a **lean headless version** and a **UI-enabled variant**. Running the headless binary with UI-specific flags triggers "unknown flag" errors. Lines [31-33](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L31) reference the `--ui` installer flag.

Verify your installed variant:

```bash
codebase-memory-mcp --version

```

The output should list `variant=ui` if the UI components are present. If not, reinstall using the `--ui` flag with the installer script.

## Integration Failures with Coding Agents

Even after successful installation, the connection to coding agents can fail if configuration updates are not properly propagated.

### Agent Configuration Not Refreshed

The installer writes MCP entries into supported coding-agent configuration files. If the agent process is not restarted after installation, it cannot see the new entries, resulting in "no index found" errors. Line [74](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L74) explicitly recommends restarting the agent.

Always restart your coding agent after running the installer. Verify the configuration entry was written correctly:

```bash
codebase-memory-mcp config list

```

## Summary

- **macOS quarantine errors** require removing the extended attribute with `xattr -d com.apple.quarantine` and setting execute permissions with `chmod +x`.
- **PowerShell execution policy blocks** are resolved by running `Set-ExecutionPolicy -Scope Process Bypass` or using the `-ExecutionPolicy Bypass` flag.
- **Daemon version conflicts** require running `codebase-memory-mcp update` and killing lingering processes with `pkill`.
- **Port binding failures** on port 9749 can be avoided by checking for conflicts with `lsof` or specifying an alternative port with `--port`.
- **Auto-index limits** in the file-watcher ([`src/watcher/watcher.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/watcher/watcher.c)) can be adjusted via `config set auto_index_limit` or disabled with `auto_watch false`.
- **Missing cache directories** must be resolved by setting `CBM_CACHE_DIR` and creating the path manually.
- **Binary variant mismatches** between headless and UI versions require reinstalling with the correct `--ui` flag.
- **Agent integration issues** are fixed by restarting the coding agent after installation to load the new MCP configuration.

## Frequently Asked Questions

### Why does codebase-memory-mcp fail with "duplicate daemon" errors?

This occurs when multiple `codebase-memory-mcp` processes with different binary builds or cache roots attempt to run simultaneously. The coordination daemon enforces strict version consistency as documented at lines [119-120](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L119). Resolve this by running `codebase-memory-mcp update` to synchronize all sessions, then terminate any stray processes with `pkill codebase-memory-mcp` before restarting.

### How do I fix the UI not starting on port 9749?

Port 9749 is the default binding for the web interface. If another service occupies this port, the UI fails to initialize. Check for conflicts using `lsof -i :9749` on Unix systems or `netstat -ano | findstr 9749` on Windows. Alternatively, launch the UI on a different port using the command `codebase-memory-mcp --ui=true --port=9750` as shown at lines [138-141](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L138).

### What should I do if the installation script is blocked on macOS?

macOS Gatekeeper adds a quarantine attribute to downloaded scripts, preventing execution. Before running [`./install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/./install.sh), execute `xattr -d com.apple.quarantine ./install.sh` to remove the security flag, and ensure the script has execute permissions with `chmod +x install.sh`. The installation documentation at line [100](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L100) references this specific remediation step.

### How do I verify which binary variant (headless vs UI) I have installed?

Run `codebase-memory-mcp --version` and examine the output for the `variant` field. If it displays `variant=ui`, the UI-enabled binary is installed. If the field is missing or shows `variant=headless`, you have the lean version that does not support UI flags. To install the UI variant, rerun the installer with the `--ui` flag as indicated at lines [31-33](https://github.com/DeusData/codebase-memory-mcp/blob/main/README.md#L31).