Docs › Troubleshooting

Troubleshooting

Start with mrsentry doctor. It checks configuration, tools, GitLab access and token scopes, the LLM, and AWS/ECR in one pass.

mrsentry doctor

mrsentry doctor            # everything
mrsentry doctor --offline  # config + local tools only
mrsentry doctor --no-llm   # skip the test prompt

✔ means the check passed, ✘ means a required check failed, and ! marks an optional item that's missing, such as a toolchain you don't use.

Exit codes

Code	Meaning	What to do
`0`	OK	Nothing.
`1`	A finding or vulnerability is at or above `--fail-on` / `output.fail_on`	Intended when you gate merges.
`2`	The MR head moved during the run	Re-run on the new head. The next pipeline does this automatically.
`3`	Git or GitLab error	Check reachability, the project path and the clone logs.
`4`	Configuration error	`mrsentry config validate`.
`5`	Authentication or permission error	Check token scopes and role. See below.
`6`	LLM error: every profile and fallback failed	Check keys, model name and quota. `mrsentry doctor`.
`7`	ECR findings stale and `ecr.on_stale=fail`	Rescan, or switch to `local`.
`8`	The fix couldn't be applied	See `mrsentry-report.json` → `fix`.

Outputs

Everything goes to mrsentry-out/ (output.dir). Choose formats with output.formats.

File	Contents
`mrsentry-report.json`	Findings, dropped candidates with reasons, scan, dependency mapping, fix result, LLM usage.
`mrsentry-overview.md`	The overview note as Markdown.
`gl-code-quality-report.json`	GitLab Code Quality report, shown in the MR widget.
`mrsentry.sarif`	SARIF 2.1.0 (add `sarif` to `output.formats`).
`mrsentry.env`	dotenv: `MRSENTRY_REVIEW_FINDINGS`, `MRSENTRY_REVIEW_MAX_SEVERITY`, `MRSENTRY_HEAD_IS_BOT_FIX`, `MRSENTRY_FIXABLE`, `MRSENTRY_FIXABLE_COUNT`, `MRSENTRY_SCAN_STALE`, `MRSENTRY_SCAN_TYPE`, `MRSENTRY_SCAN_FREQUENCY`, `MRSENTRY_IMAGE_DIGEST`, `MRSENTRY_FIX_DELIVERED` and more.
`fix-pipeline.yml`	The generated child pipeline (`run mr`).
`llm-transcripts/`	Every prompt and response, when `output.save_llm_transcripts` is on.

Common problems

401 / 403 from GitLab

The token is missing the api scope, has a role below Developer, or is CI_JOB_TOKEN, which can't post notes. mrsentry doctor prints the token's identity, scopes and access level for the project.

"GitLab token is not configured"

Set GITLAB_TOKEN or MRSENTRY_GITLAB_TOKEN. If your CI uses its own variable name, set MRSENTRY_GITLAB__TOKEN_ENV to that name.

Comments land in the overview instead of inline

GitLab rejected the line position, for example because the line is outside the diff. mrsentry falls back to a file-level comment, then to the overview. The reason is in mrsentry-report.json.

"draft notes unavailable"

Older GitLab versions don't support draft notes. mrsentry posts the discussions directly instead, with no action needed.

Exit code 2 right after a push

Someone pushed while the review ran. mrsentry never posts on stale lines. The pipeline for the new commit reviews it.

"maven dependency tree unavailable"

Maven or Gradle isn't installed in the job image. Use the full image. For private repositories, provide settings.xml / init.gradle and list the credential variables in fix.build_env_passthrough.

npm E401 while regenerating lockfiles

The runner's .npmrc refers to a token that isn't available. Pass NPM_TOKEN through fix.build_env_passthrough, or point npm_config_registry at your mirror.

Stale ECR data on scan-on-push repositories

This is expected: on-push scans are only as fresh as the last push. Use ecr.on_stale: local with the full image (Trivy included), or ask the registry owner to enable enhanced continuous scanning.

"No module named 'mcp'"

Some LiteLLM releases import an optional package for every call that uses tools. mrsentry detects this and retries without that code path, so upgrade mrsentry if you see it.

Install fails building tiktoken or hf-xet on Amazon Linux 2

Upgrade to the current installer. It detects glibc older than 2.28 and installs only prebuilt binaries.