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.
glab or gh is not authenticated
Section titled “glab or gh is not authenticated”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:
glab auth login --hostname gitlab.com # GitLabgh auth login --hostname github.com # GitHubTwo 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.
The Bash deny hook refuses a command
Section titled “The Bash deny hook refuses a command”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 isgit 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.
A pre-commit hook fails the commit
Section titled “A pre-commit hook fails the commit”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):
make format && git add <the files make format changed> && git commit -m "..." && git pushNever 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-completenessreadsdocs/specs/spec-intake.md, Blueprint’s own spec. It reportsPASS WITH WARNINGSbecause some of its decisions are still undecided.check-evalsprintsWARN agent <name> has positive cases ... and no negative controlfor 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
rulesexclude 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.