GitLab · CI/CD pipelines · pipelines and jobs API · Checked October 24, 2026

GitLab: why the pipeline or the job was refused

When you run a new pipeline through the API (POST /projects/:id/pipeline), GitLab answers 403 if your account may not create pipelines in the project at all, and otherwise 400 with its reason under message.base. Retrying, cancelling and running jobs answer in their own ways. All of this is from GitLab's source (lib/api/ci/pipelines.rb, lib/api/ci/jobs.rb and the steps that create a pipeline), read on October 24, 2026:

HTTP/1.1 400 Bad Request

{"message":{"base":["Reference not found"]}}

Running a new pipeline: 400

The reasons, in the order GitLab checks them:

• You do not have sufficient permission to run a pipeline on 'main'. Please select a different branch or contact your administrator for assistance.: the branch is protected and your account may not merge or push to it (for a protected tag: may not create it). GitLab's documentation: on a protected branch, only users allowed to merge or push to it may run pipelines, run manual jobs, and retry or cancel jobs.
• Ref is ambiguous: a branch and a tag have that name. Reference not found: there is no branch or tag by that name in the project. Commit not found: GitLab could not find the commit for it.
• Insufficient permissions to set pipeline variables: the pipeline was given variables, and your role is below the project's minimum role to use them; see who may use pipeline variables.
• Missing CI config file: the branch has no .gitlab-ci.yml, or no file by the name set in the project's CI/CD settings.
• An error in the configuration: when .gitlab-ci.yml does not validate, the message is the first error GitLab found in it.
• The pipeline did not run. Review the workflow:rules configuration for the pipeline.: workflow:rules left out the whole pipeline. GitLab 17.2 and earlier said Pipeline filtered out by workflow rules.
• The resulting pipeline would have been empty. Review the rules configuration.: the jobs' rules left out every job, so there was nothing to run. Jobs in the .pre and .post stages alone do not count as a pipeline. GitLab 17.3 to 19.2 ended the sentence with for the relevant jobs., and 17.2 and earlier said Pipeline will not run for the selected trigger. The rules configuration prevented any jobs from being added to the pipeline.

In the web interface the two rules messages link to the documentation. The API sends them as plain text.

Running a new pipeline: 403

{"message":"403 Forbidden"}: your role in the project may not create pipelines. A token without the api scope is refused with 403 too, but the answer says insufficient_scope; see which scope to add.

Retrying, cancelling and running jobs

• Retrying a pipeline (POST …/pipelines/:id/retry) runs its failed and canceled jobs again. 403 Forbidden: your account may not update the pipeline, or may not retry its jobs (on a protected branch, for example). In GitLab's current source, two more: 409 Pipeline is already being retried, when another retry of the same pipeline is still running, and 409 Error updating stale job, when a job changed while GitLab was retrying it.
• Retrying a job (POST …/jobs/:id/retry): 403 Forbidden - Job is not retryable is about the job, not about your account. In the source, a job can be retried only if it succeeded, failed or was canceled, and was not already retried, is not archived and did not have its deployment rejected. So it has not finished yet, or someone already retried it (retry its newest run instead), or it is older than the instance's archive setting. 403 Forbidden without that reason is about your account, as above.
• Running a manual job (POST …/jobs/:id/play): 400 Unplayable Job: it is not a manual or delayed job, it is archived, or it is neither waiting to be run nor finished.
• Cancelling a pipeline or a job answers 200 even when there was nothing to cancel, with the pipeline or the job as it is. The source notes this for pipelines and plans to answer with an error in a later version of the API (gitlab-org/gitlab#519143). Read the status in the answer.
• Too many requests: in the current source, retrying, cancelling and running are rate limited. Over the limit, GitLab answers 429. For jobs and for cancelling, it also sends a Retry-After header with the seconds to wait.

What to do

• Reference not found: check the branch or tag name, and push the branch first if it exists only in your clone.
• Not allowed on a protected branch: ask a maintainer, or check who may merge or push to the branch under Settings > Repository > Protected branches.
• The rules messages: look at the rules for this kind of pipeline. A pipeline run through the API has CI_PIPELINE_SOURCE api (from the New pipeline button: web), so rules that only allow push or merge_request_event leave it out.
• Missing CI config file: add .gitlab-ci.yml to that branch, or check the file name in the project's CI/CD settings.
• Job is not retryable: refresh and look at the job's newest run. If it is still running, wait for it.
• 409 on retry: wait for the other retry to finish, refresh, then retry what is still failed.
• 429: wait before trying again: the number of seconds in Retry-After, when GitLab sends it.

GitLab pipelines in IntelliJ IDEA

Pipeline Inbox for GitLab CI, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, lists your GitLab projects' pipelines with their jobs and logs, and with Pro retries, cancels and runs them. In the job list it offers Retry and Run only where GitLab says they are possible (from version 1.0.21, Run only where GitLab says your account may run the job). When GitLab will not start a new pipeline, the dialog stays open with GitLab's reason, such as the rules messages above. When GitLab refuses another change, the plugin says so with GitLab's words: for 403, that your role or a protected branch (from version 1.0.21, also a protected environment) may not allow it; at the request limit, to wait a minute (from version 1.0.21, when GitLab asks for longer, the time it opens again). From version 1.0.15, for 403 "Job is not retryable", it says instead that GitLab will not run that job again and to refresh to see its latest run. Reading is free; retrying, cancelling and running are Pro (US$1.50 a month, with a 30-day trial).

GITLAB is a trademark of GitLab Inc.; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by GitLab Inc. or JetBrains.

More: GitLab "Insufficient permissions to set pipeline variables" · GitLab job log refused or empty (403, 404) · GitLab job dropped as stuck or over its timeout · GitLab "You are not authorized to run this manual job" · GitLab pipeline failed with no jobs · GitLab "insufficient_scope" · GitLab 401 "invalid_token" · GitLab 404 "Project Not Found" · GitLab 404 "Group Not Found" · GitLab pipeline plugins for IntelliJ IDEA, compared · 日本語