Skip to content

Troubleshooting

The big picture: The six snags new adopters hit most often, each as symptom, cause and fix. Find the symptom you see; the fix is under it.

Why it matters: Most of these look like a broken Blueprint and are not. Each one is a missing login, a safety hook doing its job, or a warning that is safe to ignore.

Yes, but: this page covers setup. A failing CI job on an MR is a different problem; see CI pipeline. Back to Start a project or the quickstart.

Symptom: make doctor prints WARNING: glab is not logged in to <host> (or gh) on the forge auth line. Later, glab repo view, glab issue list and scripts/wt new <issue> fail, and the issue-collision check at push time cannot query the tracker.

Cause: the forge CLI is installed but has no login for the host your origin remote points at. make doctor picks the CLI from the origin URL (gitlab means glab, github means gh).

Fix: run the command the warning prints, then re-run make doctor:

Terminal window
glab auth login --hostname gitlab.com # GitLab
gh auth login --hostname github.com # GitHub

Two other forge auth lines are not a login problem. skipped (INFO) means there is no origin remote yet, which clears after step 2; or origin is a host whose URL contains neither gitlab nor github (a self-hosted GitLab such as git.example.com), or no forge CLI is installed. In those last cases doctor does not check a login at all, so confirm it yourself with glab auth status --hostname <host>. A WARNING ... is not installed, so login cannot be checked means origin is GitLab but only gh is installed (or the reverse): install the CLI that matches your host.

Symptom: Claude reports that a Bash call failed with pre-bash-deny: blocked. followed by a reason, for example a force-push, a bare stash, --no-verify, a hard reset, or glab mr merge.

Cause: .claude/hooks/pre-bash-deny.sh denies the operations AGENTS.md forbids, found by tokenizing the command rather than prefix-matching it. A refusal means it is working as designed.

Fix: read the reason, then pick one:

  • Use the safe equivalent it names. For stashing that is scripts/wt stash; for a rebased branch it is git push --force-with-lease.
  • If the command is one only you should run (a merge, a deliberate reset), run it yourself Type ! at the start of the Claude Code prompt, for example ! git status (use your own command). Per the Claude Code docs, a ! command runs directly without going through Claude and does not need Claude to approve it. The docs do not say how hooks treat it, so a terminal outside Claude is the plain alternative.
  • Do not ask Claude to disable the hook or edit .claude/hooks/; Bash writes there are denied too.

You are not a Maintainer on the GitLab project

Section titled “You are not a Maintainer on the GitLab project”

Symptom: scripts/gitlab-bootstrap.sh (step 3) fails with HTTP 403 - needs the Maintainer role on the project; ask a Maintainer or set it in the UI, or the settings it tries to write are grayed out in the UI.

Cause: protecting main, setting the merge method and the other project settings all need the Maintainer role. A Developer role can read the project and push to unprotected branches but cannot change those settings.

Fix: ask a project Maintainer or Owner to raise your role (Manage > Members), or to run step 3 for you. Those settings need the Maintainer role even when changed by hand in the UI, so setting them yourself is not an option without it. Once you have the role, re-run the script.

Symptom: git commit prints Format check failed — run 'make format' to fix., Lint failed, Type check failed or Secret scan failed, and no commit is created.

Cause: hooks/pre-commit only checks; it rewrites nothing. It runs make gitleaks-check, then make format-check, make lint and make typecheck, and fails the commit when one reports a problem. Each of the last three is skipped while it is still the Makefile stub (format-check: skipped (not configured)). A commit can also fail because your own formatter, or a hook you added, rewrote files: the staged version and the rewritten version then differ.

Fix: run make format (or let your formatter finish), re-stage the files it changed, and commit again. For Lint failed or Type check failed, fix what make lint or make typecheck reports, re-stage, and commit again. Chain with &&, not ;, so a failed commit never reaches git push (a ; would publish an empty branch):

Terminal window
make format && git add <the files make format changed> && git commit -m "..." && git push

Never bypass the hook with --no-verify; the deny hook above refuses it for Claude, and AGENTS.md forbids it for agents. If the secret scan fails, remove the secret; add an allowlist entry to .gitleaks.toml only for a documented false positive.

make pre-push-checks prints WARN lines on a fresh clone

Section titled “make pre-push-checks prints WARN lines on a fresh clone”

Symptom: make pre-push-checks exits 0 and no check fails, but the output contains WARN lines you did not cause.

Cause: two checks warn about content that ships with the template and that you have not reset yet:

  • check-spec-completeness reads docs/specs/spec-intake.md, Blueprint’s own spec. It reports PASS WITH WARNINGS because some of its decisions are still undecided.
  • check-evals prints WARN agent <name> has positive cases ... and no negative control for each agent whose eval cases include no negative control.

Fix: none needed; a WARN does not fail the run. The spec warnings go away when customize.sh --init (or --reset-template) removes Blueprint’s own spec. The evals warnings stay until your project adds a negative-control case for each agent or removes evals/. Treat a nonzero FAIL or INCOMPLETE count, a check-evals: FAIL line, or a WARN from a file you wrote, as real.

My first pipeline is stuck in pending or created no jobs

Section titled “My first pipeline is stuck in pending or created no jobs”

Symptom: the MR pipeline stays pending, shows jobs that never start, or has no jobs at all, and nothing in your diff explains it.

Cause: most often runner availability, not a Blueprint job failing. A pipeline that failed at creation has zero jobs and tested nothing, so conclude nothing about your code from it. On GitLab.com the usual causes are:

  • Instance runners are turned off for the project (Settings → CI/CD → Runners; see runner scope).
  • Identity verification is required before a free-plan account can run jobs on GitLab-hosted runners (tier-dependent; the error reads Identity verification is required in order to run CI jobs, see debugging pipelines).
  • The namespace used its monthly compute minutes, so pending instance-runner jobs are dropped (compute usage).
  • No runner matches the job’s tags, or none is online (self-managed). GitLab drops such a job after about an hour (job troubleshooting).
  • An invalid or empty pipeline configuration: the pipeline list shows a YAML error on a pipeline that failed at creation.
  • A pipeline with no jobs after evaluation does not run at all, for example when rules exclude every job (debugging pipelines).

Fix: open the pipeline and read the banner or the job’s status message, then fix the matching cause above. For your own runners see Private CI runners. After verification or a runner change, push a new commit or run a new pipeline. A job that runs and fails is a different problem: read its log.

make doctor warnings that are safe to ignore

Section titled “make doctor warnings that are safe to ignore”

Symptom: make doctor exits cleanly but prints one or more WARNING or INFO lines.

Cause: doctor separates MISSING (a hard prerequisite) from WARNING (a degraded but working setup) and INFO (nothing wrong). Only MISSING blocks you.

Fix: treat these as safe to ignore for now, and the rest as real:

Line Level Safe to ignore when Clears when
git hooks not installed WARNING you have not run make setup yet (quickstart step 1) you run make setup
direnv missing WARNING you will source .envrc by hand in each worktree you install direnv (optional)
.env missing WARNING .env.example lists keys you do not need yet you run cp .env.example .env
.env not needed INFO always: .env.example has no required keys never needed
forge auth skipped INFO there is no origin remote yet, the host is not recognized as GitLab or GitHub, or no forge CLI is installed you add the remote (step 2); otherwise check the login yourself
shellcheck missing WARNING CI runs it anyway; the local check is a no-op you install it (optional)
jq missing WARNING until you open an MR (step 8); then install it, because the pre-MR security hook blocks every glab mr and glab api command without it: Pre-MR security gate: BLOCKED because jq is not installed or not on PATH. you install it
gitleaks missing WARNING CI’s gitleaks-scan job still enforces it; the local secret scan in the pre-commit hook is a no-op you install it (recommended before your first real commit)

Do not ignore a MISSING line, a glab / gh warning once you use a real GitLab project, a logged-out forge auth (see above), or an AGENTS.md warning: those mean a gate silently does less than it should.