Troubleshooting & FAQ
Nothing happens when I assign the bot
Section titled “Nothing happens when I assign the bot”Work through this checklist in order.
1. Confirm the webhook is registered and delivering. In your GitLab project, go to Settings → Webhooks, open the webhook you registered during onboarding, and check the Recent deliveries tab. If there are no entries, GitLab is not sending events — either the webhook is not registered, or the project URL does not match the target project.
2. Confirm the webhook is subscribed to the right events. The webhook must have the Issues events or Merge request events checkbox enabled (depending on what you are assigning). If the relevant event type is not checked, GitLab will not send the payload and no job will be created.
3. Confirm the webhook secret matches. If the webhook secret configured in GitLab does not match the one Mate is expecting, Mate silently drops the payload (it does not reply with an error to avoid leaking information). Re-copy the secret from the console and update the webhook in GitLab.
4. Confirm the bot is actually assigned. Mate only fires when the bot account is among the assignees. Assigning a different user, or assigning the bot as a reviewer rather than an assignee, does not trigger a job.
5. Confirm a matching trigger exists.
If the webhook is delivering but no job appears in the console, there may be no trigger configured for this event. Events that match no trigger are not recorded anywhere in the console — the Jobs page only shows dispatched jobs. Use GitLab’s webhook Recent deliveries log to correlate: a response code of 200 with no corresponding job means the payload was accepted but no trigger matched; a response code of 401 means the webhook secret is wrong. Make sure your .mate.yml (or console config) has a trigger for issue_assigned or mr_assigned with the correct agent:.
Mentions don’t fire a job
Section titled “Mentions don’t fire a job”The mention must be the bot’s exact GitLab username, prefixed with @, in an issue or MR comment body. Username matching is case-sensitive.
Example: if the bot account is gitlab-username: mate-junior, then @mate-junior triggers the job. @Mate-Junior, @mate_junior, or mentioning the bot in a commit message or description (instead of a comment) will not trigger anything.
Also confirm that:
- A
comment_mentiontrigger is configured in your agent config. - The Note events checkbox is enabled on the webhook in GitLab.
A label trigger doesn’t fire
Section titled “A label trigger doesn’t fire”label_applied requires two conditions to both be true:
- The label being added matches the
label:field in your trigger definition (shell-glob pattern, e.g.needs-*). - The bot account is already an assignee on the issue or MR at the time the label is applied.
If the bot is not an assignee, Mate ignores the label event entirely. Assign the bot first, then apply the label — or configure a separate issue_assigned / mr_assigned trigger so assignment itself kicks off a first job.
A job was canceled unexpectedly
Section titled “A job was canceled unexpectedly”Open the job in the console and check the cancellation reason. Common causes:
Timeout / wallclock limit. Each job has a maximum wall-clock duration set by the agent’s timeout: field, or by policies.default_timeout when no per-agent value is set; when this limit is reached the job is canceled with reason timeout. Independently, a job that produces no harness activity for 5 minutes is canceled by the no-progress watchdog (also reason timeout) — this usually means the agent is stuck or the container lost connectivity. Per-job credentials also carry a hard ceiling of roughly one hour from dispatch time, after which the MCP layer rejects tool calls even if the configured timeout has not fired. Check the job events log for the last recorded activity to distinguish between these three cases.
Spend cap reached (OpenRouter). If you configured an OpenRouter provisioning key with openrouter_default_limit_usd, the per-job sub-key has a spend ceiling. When that ceiling is hit, OpenRouter stops authorizing requests — the job does not receive a clean cancellation signal; instead it fails mid-run with LLM provider or credit errors visible in the job event log. Raise or remove the limit in your console config if jobs are hitting it legitimately.
Admin or shutdown cancel. Mate itself may have been restarted during the job (reason: shutdown). Jobs that were already running when the service stopped are marked failed and are not re-queued. Jobs that were still waiting in the queue (not yet dispatched) survive a restart and will be dispatched when the service comes back up.
A job errored before doing anything
Section titled “A job errored before doing anything”If a job transitions to failed very quickly — within a few seconds of being dispatched — the most likely cause is an invalid or exhausted LLM credential.
When using OpenRouter with a provisioning key, Mate mints a per-job sub-key at dispatch time. If the provisioning key is revoked, over-quota, or has expired, the dispatch is blocked and the job is immediately marked failed. Mate does not fall back to any other key.
If using passthrough mode (a regular API key in your agent env), an invalid key is detected by the agent runtime at its first API call, not at dispatch time — the job will start but the agent will log a credential error before completing any work.
In both cases: check the job events log for the specific error, rotate the key in your LLM provider’s console, and submit the new key via the onboarding wizard (currently the only path for updating LLM credentials in the Mate console).
The agent says it can’t do something
Section titled “The agent says it can’t do something”The agent operates under an explicit permission set. If it reports that an action is not allowed (commenting, creating a branch, opening an MR, merging, closing an issue), the required authority is likely not granted to the agent or trigger.
See Permissions for how to configure the effective authority set. Note that approving MRs is not a grantable authority — see the FAQ entry below.
Too many jobs queued / jobs are not starting
Section titled “Too many jobs queued / jobs are not starting”Each tenant has a concurrency limit (configured in policies.concurrency). When that many jobs are running simultaneously, new jobs queue up and wait for a slot to open.
Additionally, each repository has a cooldown period (configured in policies.cooldown). After a job completes on a repository, no new job on the same repository can start until the cooldown elapses.
The console Jobs page lists all jobs for the tenant. Queued work appears there as jobs start dispatching; it does not show aggregate queue depth or running-job counts as separate metrics.
I’m stuck on the waitlist
Section titled “I’m stuck on the waitlist”Mate is in closed beta. Signups beyond the current capacity cap land on a FIFO waitlist and are admitted manually as slots open. There is no way to skip the queue. If you signed up and have not heard back, check your email (including spam). For other questions, see Support.
Can the agent approve MRs?
Section titled “Can the agent approve MRs?”No, and this is intentional. Merge request approval is a deliberate human gate. Mate’s permission model does not include an approve_mr authority, and no configuration can grant it.
During the closed beta, the agent’s active tool surface covers read operations and commenting. Write authorities (push, merge, and others) are accepted in agent config and widen the clone-token scope, but the corresponding tools are not yet enabled — see Permissions for the current set. The approval step always requires a human regardless.
Which LLM models can I use?
Section titled “Which LLM models can I use?”Any model your connected provider supports. See Models and BYOK for supported providers and how model IDs are formatted.
Can I use a self-managed GitLab instance?
Section titled “Can I use a self-managed GitLab instance?”Yes. During tenant setup, you configure the gitlab_base_url for your instance (for example, https://gitlab.yourcompany.com). All GitLab API calls from Mate go to that base URL. There is no requirement to use gitlab.com.
Is my code sent to Mate?
Section titled “Is my code sent to Mate?”The agent has access to your repository through a short-lived clone token that is scoped to the specific project and expires when the job ends. Mate’s infrastructure facilitates the job container lifecycle, but LLM calls go directly from the job container to your configured provider endpoint — Mate does not proxy or log LLM traffic. For the full security model, see Security.