GuidesCLITroubleshooting

Start any investigation with:

mesrai status
mesrai auth status
mesrai review --verbose    # or any command with --verbose

mesrai status shows the consolidated state (auth mode, org, repo, hook, version). --verbose prints the resolved API URL and per-request details.

Common Errors

Command not found: mesrai

The CLI isn’t on your PATH. Reinstall with your package manager’s global flag, or use npx @mesrai/cli <command> for one-off runs.

  • npm install -g @mesrai/cli
  • yarn global add @mesrai/cli
  • pnpm add -g @mesrai/cli
  • bun add -g @mesrai/cli

If you installed via the skill installer, re-run curl -fsSL https://review-skill.com/install | bash to fix PATH entries.

AUTH_REQUIRED or 401 Unauthorized
  • Run mesrai auth status to see the current mode.
  • If using a team key, verify it’s still active at app.mesrai.com/organization/cli-keys.
  • If using personal login, try mesrai auth login again — the refresh token may have expired.
  • For CI, confirm MESRAI_TOKEN (or MESRAI_TEAM_KEY) is set in the environment the pipeline runs in.
  • If self-hosted, confirm MESRAI_API_URL points to the correct instance.
NOT_IN_GIT_REPO

mesrai review requires a git working directory. cd into a repo or initialize one with git init. For mesrai config repo commands, you can pass owner/repo explicitly instead of ..

Review takes very long or seems to hang

Large branches (hundreds of files, thousands of lines) can take several minutes. The default request timeout is 60 minutes — you should see progress in verbose mode.

  • Use --verbose to confirm the request is in flight.
  • For very large diffs, prefer --branch <base> or --commit <sha> over working-tree mode: these let the backend clone the same commit instead of receiving inlined file contents.
  • Override the timeout with MESRAI_REQUEST_TIMEOUT_MIN=90 mesrai review if needed.
  • Split work across smaller branches when practical.
Files are being skipped from the review

Review honors the ignore-files patterns configured in mesrai config repo. List current settings with:

mesrai config repo show

You can add or remove patterns:

mesrai config repo add-ignore-file . "**/*.generated.ts"
mesrai config repo remove-ignore-file . "**/*.generated.ts"

Binary files, images, and lockfiles are skipped by default.

Rate limit reached / Trial exhausted

Trial mode allows 5 reviews per day. Sign in with mesrai auth login or configure a team key via mesrai auth team-key --key mesrai_xxxxx to raise limits. mesrai auth status prints your current usage.

API returned invalid response (expected JSON, got HTML)

Your MESRAI_API_URL is hitting a reverse proxy or Cloudflare Access page instead of the API. Check:

  • The URL path (no stray /api, /v1, etc.).
  • Cloudflare Access credentials (CF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRET) if applicable.
  • That the proxy forwards Authorization and CF-Access-* headers intact.
HTTPS required for API URL

The CLI rejects non-HTTPS API URLs for everything except localhost and 127.0.0.1. Provision a valid TLS certificate for your self-hosted instance, or use http://localhost:<port> for local development.

Pre-push hook is not running
  • Confirm installation: mesrai hook status.
  • Make sure .git/hooks/pre-push is executable.
  • Other hook managers (Husky, Lefthook, pre-commit) may overwrite .git/hooks/pre-push. Either chain them or reinstall with mesrai hook install --force.
  • Skip the hook for a single push: MESRAI_SKIP_HOOK=1 git push.
Decisions (memory) hooks aren't capturing
  • Run mesrai decisions status to see which agents are wired up.
  • Re-run mesrai decisions enable --force to reinstall integration files.
  • For Codex, ensure ~/.codex/config.toml contains the notify = ["mesrai", "decisions", "capture", ...] line, or pass --codex-config <path>.
  • Check the agent actually emits turn-complete events (some older Claude Code configurations don’t).
Device limit reached

Self-hosted instances can enforce device limits per organization. Ask your admin to increase the limit or remove unused devices from the dashboard.

Exit Codes

Use these in scripts and CI pipelines.

CodeMeaning
0Success. No issues found, or issues were found but below --fail-on.
1Issues found at or above the --fail-on severity.
2CLI usage error (invalid flag, missing argument).
3Authentication or authorization failure.
4Network or API error (timeout, 5xx, invalid response).
5Not in a git repository, or no changes to review.

For CI, pair --fail-on error with --format json and --output review.json to surface structured results as pipeline artifacts without affecting the exit code logic.

Debugging Tips

  • --verbose on any command prints the resolved API URL, request IDs, and timings.
  • mesrai schema outputs the machine-readable command schema — useful when your agent reports a missing flag.
  • --agent enforces deterministic, machine-readable output; combine with --format json when scripting.
  • MESRAI_VERBOSE=true persists verbose mode across multiple commands in a session.

Getting Help

  • Report bugs: github.com/mesraiofficial/cli/issues
  • Feature requests, configuration questions: your Mesrai account manager, or support@mesrai.com.
  • For self-hosted deployments, include mesrai status --verbose output when filing an issue.
Decision memoryOverview