Meridian Troubleshooting: Diagnose and Fix Common Issues

Step-by-step fixes for installation failures, daemon crashes, Jira and GitHub auth errors, MCP server issues, and macOS permission problems.

When something goes wrong with Meridian, start with meridian doctor. It runs the full suite of environment health checks — binary presence, plist validity, running processes, database existence, Python venv, and MCP build — and tells you exactly which check failed and what to do about it.

meridian doctor

The sections below cover the most common failure patterns in more detail.

---

Installation & Setup

macOS Gatekeeper blocks the binary on first launch (unsigned v1)

The current Meridian release ships an unsigned binary, so macOS may quarantine it on first launch with a “cannot be opened because the developer cannot be verified” error.

Clear the quarantine attribute and restart:

xattr -dr com.apple.quarantine ~/.meridian/app
meridian restart

`npm install -g` fails with EACCES

This happens when your npm global prefix is root-owned — typical with the stock macOS Node install at /usr/local. Running npm install -g (with or without sudo) is not the right fix; use the bootstrap one-liner instead. It redirects the prefix to ~/.npm-global (user-owned), patches your shell profile so the change persists across terminals, and then installs Meridian and runs setup:

curl -fsSL https://raw.githubusercontent.com/Meridiona/meridian/main/scripts/bootstrap.sh | bash

The script is idempotent and never uses sudo. Re-running it after a failed install is safe.

`meridian: command not found` after install

npm install -g @meridiona/meridian puts the CLI on the npm global bin path. If your shell can’t find it, that directory is not on your PATH.

1. Find the npm global bin: npm bin -g (typical values: /usr/local/bin, ~/.npm-global/bin, or ~/.local/bin).

2. Add it to your PATH in ~/.zshrc (or ~/.bashrc):

   export PATH="$(npm bin -g):$PATH"
   

3. Open a new shell or source ~/.zshrc.

The bootstrap one-liner (curl -fsSL .../bootstrap.sh | bash) does this automatically — re-run it if you’d rather not edit your profile by hand.

`meridian setup` fails at the Homebrew step

meridian setup uses Homebrew to install system dependencies (Python 3.11, ffmpeg, screenpipe). If it fails at this step:

1. Make sure you have an active internet connection.
2. Ensure Xcode Command Line Tools are installed:

xcode-select --install

If the tools are already installed, the command exits immediately with a message to that effect. Otherwise, follow the on-screen prompt and re-run meridian setup after the installation completes.

Source build: Rust or Python setup fails

These errors only apply to contributors who cloned the repo and ran ./install.sh instead of installing from npm. The npm distribution ships a prebuilt binary and never needs Rust or a Python toolchain on your machine.

Rust toolchain: rustup show should report a stable toolchain for aarch64-apple-darwin. If rustup itself is missing, install it from rustup.rs. rust-toolchain.toml in the repo pins the required version.

Python: the source build requires Python 3.11 (brew install python@3.11 or pyenv install 3.11). After installing, re-run ./install.sh.

---

Daemon & Runtime

Daemon exits immediately on startup

The Rust daemon TCP-connects to the MLX inference server before entering its poll loop. If the MLX server is not running, the daemon exits immediately with an error message in the log.

Fix — restart the stack so launchd brings the MLX server back up:

meridian restart
meridian logs mlx-server -f

Wait until you see server: MLX model ready (this can take a few minutes on the very first run while the ~6 GB model downloads, then ~5 seconds from cache thereafter).

If the MLX plist is missing entirely (e.g. meridian status reports not installed), re-run meridian setup to re-register the launchd agents.

Alternatively, if you do not need session classification, set CLASSIFICATION_ENABLED=false in ~/.meridian/app/.env and restart:

meridian config edit   # set CLASSIFICATION_ENABLED=false
meridian restart

Run meridian doctor afterwards to confirm everything is healthy.

How to check daemon health

Two commands give you a complete picture:

meridian status    # Is the process running?
meridian doctor    # Are all dependencies satisfied?

For live log output:

meridian logs daemon -f          # stdout (info/debug)
meridian logs daemon-error -f    # stderr (errors and panics)

Sessions are not appearing in the database

If meridian status shows the daemon is running but no sessions appear in ~/.meridian/meridian.db, check the following:

1. Is screenpipe running?

meridian status    # look for com.meridiona.screenpipe

2. Does the screenpipe database exist?

ls -lh ~/.screenpipe/db.sqlite

If the file is missing, screenpipe has not recorded any frames yet. Ensure screenpipe has Screen Recording permission (see the macOS Permissions section below) and that it has been running long enough to produce data.

3. Is SCREENPIPE_DB pointing to the right path?

meridian config edit    # verify SCREENPIPE_DB if you customised it

---

Integrations

Jira: 401 Unauthorized

A 401 from the Jira API means either JIRA_EMAIL or JIRA_API_TOKEN is wrong, or the token has been revoked.

1. Open ~/.meridian/app/.env with meridian config edit.
2. Verify that JIRA_EMAIL matches the email address of the Atlassian account that owns the token.
3. Regenerate the token at id.atlassian.com/manage-profile/security/api-tokens and paste the new value into JIRA_API_TOKEN.
4. Restart: meridian restart.

Jira: no Jira tasks are loading

If the Jira connector is authenticated but no Jira tasks are appearing in session classifications:

1. Check JIRA_PROJECT_KEYS — if set, ensure the keys match exactly (e.g. KAN, not kan).
2. Confirm that the projects have open issues in the configured statuses.
3. Force a full refresh without restarting the daemon:

python3 scripts/refresh_pm_tasks.py

You can also run a targeted refresh with custom JQL:

python3 scripts/refresh_pm_tasks.py --jql "project=KAN ORDER BY updated DESC"

GitHub: 401 Unauthorized

A GitHub 401 means the personal access token is expired, revoked, or was created without the repo scope.

1. Go to github.com/settings/tokens and create a new classic PAT with at minimum the repo scope.
2. Update GITHUB_TOKEN in ~/.meridian/app/.env via meridian config edit.
3. Restart: meridian restart.

Linear: no tasks are loading

1. Verify LINEAR_API_KEY is set correctly in ~/.meridian/app/.env.
2. Check LINEAR_TEAM_IDS — if set, confirm the team IDs are correct (visible in Linear’s workspace settings URL).
3. Ensure the teams have open issues in a status that the connector picks up.
4. Check the daemon log (which handles all tracker sync) for error messages:

meridian logs daemon -n 100
meridian logs daemon-error -n 100

---

MCP Server

AI tool says Meridian is not found or DB is missing

This error means the MCP server process could not find ~/.meridian/meridian.db.

1. Confirm the daemon is running and has processed at least one poll tick:

meridian status
meridian logs daemon -n 50

2. Check that the database exists:

ls -lh ~/.meridian/meridian.db

3. If you edited the MCP config file (~/Library/Application Support/Claude/claude_desktop_config.json), verify that the path in args points to the actual repo location:

{
  "mcpServers": {
    "meridian": {
      "command": "node",
      "args": ["/your/actual/path/to/meridian/packages/meridian-mcp/dist/index.js"]
    }
  }
}

Use an absolute path — ~ is not expanded by all MCP hosts.

MCP server build fails

If packages/meridian-mcp/dist/index.js is missing or stale, rebuild it:

cd packages/meridian-mcp
npm install
npm run build

Then restart your MCP-compatible AI tool so it picks up the rebuilt server.

---

macOS Permissions

screenpipe is not recording — no frames in the database

screenpipe requires Screen Recording permission to capture frames. Without it, the database stays empty and Meridian has nothing to process.

Run the guided permissions walkthrough:

meridian permissions

The command opens the Screen Recording and Accessibility System Settings panes in sequence and waits for you to confirm each one. (Audio capture is disabled, so no Microphone permission is required.) After granting access, restart the stack:

meridian restart

You must restart screenpipe after granting Screen Recording permission. The permission change does not take effect for a running process.

---

Dashboard

http://localhost:3939 is not loading

1. Check whether the UI service is running:

meridian status    # look for com.meridiona.ui

2. If it is not running, check the logs:

meridian logs ui
meridian logs ui-error

3. If the UI plist is missing entirely (not installed), re-run meridian setup to re-register the launchd agents.

4. If the port is in use, set MERIDIAN_UI_PORT in ~/.meridian/app/.env to something else and restart:

meridian config edit
meridian restart

---

meridian doctor is always the best first step for any issue. It checks every dependency and running service in one command and tells you exactly what needs fixing.