Troubleshooting

Audience: a user on a starter install who saw a message and wants to know what it means.

How to use this page: search it for the message you saw. Each row starts with the message as himmel prints it, where <branch> or <n> stands for a value from your project. The row says why you see it and what to do.

Refused by a guardrail? A hook or git gate that stops an edit, a commit on main or a push to main is covered on When a guardrail stops you. This page does not repeat those refusals.

Want a health check? Run /himmel-doctor in Claude Code. It prints a report grouped by severity, and each finding names its own fix. The findings a starter install can show are in Checking the install.

While installing

What you see	Why	The fix
WARN: 'bun' not found — qmd search will be skipped;	qmd, the local notes search, runs on bun. A starter install does not use it.	Nothing to do. To add notes search later, install bun from https://bun.sh and run the install again.
The install is uncommitted on <branch>, which the git gates now refuse commits on.	The install did not commit itself: you answered no, or it ran without a terminal and could not ask. The git gates it just installed refuse commits on the default branch the message names, apart from this one.	Run the command printed on the next line, Commit it once with: …. It makes the one allowed commit on that branch.

Starting a worktree

What you see	Why	The fix
WARN new-worktree: no 'origin' remote - branching from local '<branch>'	The project has no origin remote, so the new worktree branches from your local default branch (main or master), the one the warning names.	Nothing to do for a local project. Once the project has a remote that holds its default branch, run git remote add origin <url> and git fetch origin; later worktrees branch from the remote copy of that branch.
WARN new-worktree: uniqueness-vs-merged-PR check skipped (forge unreachable)	Before it creates a branch, scripts/worktree.sh asks the forge whether a merged pull request already used the name, and got no answer: there is no GitHub remote, gh is missing or signed out, or the forge timed out.	Nothing to do: the check is skipped, not failed, and the worktree is still created unless a later step fails. The check runs again once the forge answers; for a GitHub project, gh auth status should show you signed in.

Committing

What you see	Why	The fix
COMMIT REJECTED: no ticket reference matched:	Every commit message needs a ticket reference by default. The pattern printed right after the message is the one in force. On a starter install it is # and a number, such as #1; your own pattern, a Jira project key or a tracker prefix changes it.	Add a reference that matches the printed pattern, for example git commit -m "feat: add hello #1". To drop the rule for every project on this machine, run himmelctl config set commit.tracker none.
COMMIT REJECTED: message does not match conventional commit format.	Commit messages follow the conventional format type(scope): message, with a type such as feat, fix, docs or chore.	Reword the message, for example git commit -m "docs: explain the setup #1". The refusal lists every type it accepts.

Checking the install

himmelctl status lists every item the install manages. Each row is green, degraded, red or n/a.

What you see	Why	The fix
of them desired but not set up: see the n/a rows above	Your install profile asks for these items, but they are not set up yet. On a starter install most are opt-in, such as the Jira keys, or appear on first use, such as the handover folder.	Read the n/a rows: each names what turns it green. An opt-in item you do not use can stay n/a.
<n> himmelctl install/wiring finding(s) (delegated from 'himmelctl status --json')	/himmel-doctor found items that himmelctl status reports red or degraded.	Run himmelctl status to see them, then himmelctl ensure in a terminal (himmelctl ensure --yes without one). It installs or rewires each finding it has an action for and prints a hint for the rest, which you fix by hand.
hook(s) wired to a bare interpreter not installed on this host:	A hook in your settings starts with a program this machine lacks, so every session prints <interp>: command not found and the hook never runs.	Install the program it names, or run the install again so it rewires the hook.
plugin(s) enabled but not installed:	Your settings turn on a plugin that Claude Code has not installed.	Install it with claude plugin install <id>, or set it to false in the settings file the finding names.