Diagnosing Setup Issues

The maeris doctor command runs a comprehensive health check on your Maeris MCP installation. It verifies every component of your setup and provides actionable error messages when something is misconfigured.

Running the Doctor Command

Run the diagnostics check from any directory:

maeris doctor

The command will run through each check sequentially and print a pass/fail result for each one. A typical successful output looks like:

[✓] Python version: 3.11.4 (OK)
[✓] maeris package: 1.2.0 installed
[✓] .mcp.json found in project root
[✓] Auth token: valid (expires 2026-06-01)
[✓] Maeris server reachable: api.maeris.io (200 OK)
[✓] Application context: my-web-app

All checks passed. Maeris MCP is ready to use.

What the Doctor Checks

Python version — Confirms Python 3.10 or higher is installed and on PATH
Package installation — Verifies the maeris package is installed and importable
.mcp.json presence — Checks that the MCP configuration file exists in the current project root
.mcp.json validity — Validates the JSON structure and ensures the maeris server entry is correctly formed
Auth token — Confirms a valid, non-expired authentication token is stored locally
Server reachability — Pings the Maeris API to confirm network connectivity
Application context — Verifies that the CLI is linked to a valid Maeris application

Common Errors and Fixes

Python version too old

[✗] Python version: 3.9.7 — requires 3.10 or higher

Fix: Upgrade Python to 3.10 or higher from python.org/downloads. On macOS you can also use brew install python@3.11.

.mcp.json not found

[✗] .mcp.json not found in current directory

Fix: Make sure you are in your project root directory and run maeris app init. See the Initialize Your Project guide.

Auth token missing or expired

[✗] Auth token: not found or expired

Fix: Run maeris auth login to complete the OAuth2 flow and obtain a fresh token. See the Authentication & Login guide.

Server unreachable

[✗] Maeris server unreachable: api.maeris.io (connection timeout)

Fix: Check your internet connection and verify that api.maeris.io is not blocked by a firewall or VPN. If you are behind a corporate proxy, configure the HTTPS_PROXY environment variable.

maeris command not found

zsh: command not found: maeris

Fix: The pip bin directory is not on your PATH. Either reinstall with pip install maeris and follow the PATH instructions output by pip, or run python3 -m maeris --version to confirm the package is installed. See the Installing Maeris MCP guide.

Verbose Mode

For more detailed diagnostic output, run the doctor command with the verbose flag:

maeris doctor --verbose

Verbose mode prints the full path to the maeris binary, token storage location, .mcp.json contents, and raw HTTP response codes from the server ping — useful when filing a support ticket.

Still Having Issues?

If the doctor command passes all checks but tools still aren't working in your editor, make sure you have restarted your editor after running maeris app init. Related guides: