Skip to content

Troubleshooting & FAQ

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 Work item events (older GitLab: Issues events), Merge request events, Comments or Pipeline events checkbox enabled, depending on the trigger. 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 rejects the payload with a 401 and no body. Re-copy the secret from the console and update the webhook in GitLab.

4. Confirm the right action was taken. An assignment trigger (assigned: true) fires when the managed account is newly added as an assignee. Requesting its review fires only a review_requested: true trigger, and assigning a different user fires nothing.

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 such as on: issue with assigned: true (or on: merge_request) with the correct agent:. Also check the subscription: mates run jobs once the workspace has a plan. Without one, Mate comments This workspace has no active Mate subscription, so this action wasn't processed. on the issue or MR.


The mention must be the managed account’s exact GitLab username, prefixed with @, in an issue or MR comment body. Username matching is case-sensitive.

Example: if the account is mate-junior, then @mate-junior triggers the job. @Mate-Junior, @mate_junior, or mentioning the account in a commit message or description (instead of a comment) will not trigger anything.

Also confirm that:

  • An on: note trigger with mention: true (the default) is configured in your config.
  • The Comments checkbox is enabled on the webhook in GitLab.

There is no standalone label trigger: label: is a filter on on: issue and on: merge_request triggers. A label trigger such as

- on: merge_request
action: [update, open]
label: "agent/review"
account: mate-security
agent: mate-security

fires when an MR event arrives for an MR whose labels match the glob. Check that account: names a registered managed account (it is required here unless the workspace has exactly one account), that the glob matches the label, and that Merge request events are enabled on the webhook.


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 neither is set the limit is one hour. When it is reached the job is canceled and the GitLab status note names the limit and how to raise it (timeout: on the agent or policies.default_timeout in the workspace config). Independently, a job that makes no progress for 20 minutes (the default) is canceled by the no-progress watchdog (also reason timeout) — this usually means the agent is stuck or the container lost connectivity. The job’s tool credential expires with the timeout, after which the tool service rejects tool calls. Check the run log for the last recorded activity to tell the cases apart.

Spend cap reached (OpenRouter). On deployments where the operator configured an OpenRouter provisioning key, each job gets its own sub-key capped at the operator’s openrouter_default_limit_usd. 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 run log. This is not a console setting: ask the operator to raise it. With your own workspace key, spend limits are the ones you set with your provider.

Reassigned. Removing the managed account as assignee or reviewer while a job runs stops it; the GitLab note says Stopped: reassigned, so a human can take over.

Admin or shutdown cancel. Mate itself may have been restarted during the job. 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.


If a job ends as ERRORED or FAILURE very quickly — within a few seconds of being dispatched — the most likely cause is an LLM key problem.

  • Incompatible key and backend. Some key kinds cannot run some backends (for example an Anthropic key cannot run codex). Mate fails the job before starting it and posts the reason on the GitLab note. See Models and BYOK.
  • Invalid or exhausted key. The agent only finds out at its first model call, so the job starts and then logs a credential error from your provider. Check the run log for the specific error, rotate the key in your provider’s console, and submit the new one under Settings → LLM key.
  • Wrong model ID. Mate does not validate model IDs; your provider rejects an unknown one when the job runs, and the error appears in the job’s status note.

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. Approving MRs is an opt-in authority — see the FAQ entry below.


Too many jobs queued / jobs are not starting

Section titled “Too many jobs queued / jobs are not starting”

Your plan’s mates bound how many jobs run at once, and you can cap individual projects with policies.concurrency (a map of project path to cap). When the limit is reached, new jobs queue up and wait for a slot to open.

Additionally, policies.cooldown paces job starts per repository: events queue and dispatch as the window clears. Jobs on the same issue or MR also run one at a time.

The console Jobs page lists all jobs for the workspace. Queued work appears there as jobs start dispatching; it does not show aggregate queue depth or running-job counts as separate metrics.


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.


Only if you opt in. Add approve_mr to the agent’s permissions:; by default it is not granted. GitLab’s own approval rules (such as “prevent approval by author”) still apply.

Write authorities (push_branch, open_mr, merge, and the others) are live, so you decide how much an agent may do; approval is opt-in. See Permissions.

Any model your connected provider supports; Mate does not restrict or validate model IDs. See Models and BYOK for key providers, backends, and how model IDs are formatted.

Yes. During workspace setup, you set the GitLab 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.

The agent has access to your repository through a short-lived clone token that is scoped to the specific project and is revoked when the job ends. Mate’s infrastructure runs the job container, and LLM calls go from the job to your configured provider endpoint under your own key — Mate does not store LLM traffic. For the full security model, see Security.