Troubleshooting Common no-mistakes Errors in the Go-Based CLI

Most runtime failures in no-mistakes stem from three subsystems: strict configuration parsing in internal/config/config.go, repository trust validation in internal/daemon/manager.go, and pipeline step pre-condition checks in the internal/pipeline/steps/ package.

The no-mistakes CLI from the kunchenguid/no-mistakes repository coordinates a daemon, pipeline executor, and agent integrations to automate Git workflows. When troubleshooting common no-mistakes errors, you will encounter issues spanning YAML unmarshalling, detached-HEAD worktree management, and force-push lease violations. Understanding the specific source files and function names that raise these errors allows you to diagnose and fix problems without deep codebase exploration.

Configuration Parsing Errors

The CLI prints failed to parse .no-mistakes.yaml: <error> and exits when the strict Config struct in internal/config/config.go encounters unknown fields, type mismatches, or malformed YAML during unmarshalling.

LoadConfig rejects configurations that do not match the expected schema exactly. For example, using auto_fix instead of auto_fix: (missing colon) or passing ci_timeout: true instead of a duration string triggers a parsing failure.

Validate your configuration before deployment:

cat .no-mistakes.yaml | go run github.com/go-yaml/yaml/v3@latest -c

If the error mentions an unknown field, rename the key to match the struct fields defined in config.go. If a value has an incorrect type, ensure ci_timeout uses a duration string like 10m rather than a boolean. You can test configurations safely using the --config flag to point to a temporary file without overwriting the source repository's YAML.

Repository Trust and Daemon Failures

The daemon logs trusted config missing; aborting commands when loadTrustedRepoConfig in internal/daemon/manager.go fails to fetch the default-branch tip and resolve the exact commit SHA. The system reads .no-mistakes.yaml from a pinned commit SHA, not the working directory.

Fix this by ensuring the remote is reachable and the default branch contains a valid configuration:

git remote update origin
git fetch origin --prune
git rev-parse origin/$(git symbolic-ref --short HEAD)

To allow the pushed branch's commands temporarily, set allow_repo_commands: true in the default-branch configuration (not the feature branch). The trust logic is tested in internal/config/config_repo_trust_test.go.

Pipeline Execution Errors

The pipeline executor runs ordered steps (rebase, push, ci, auto-fix) from the internal/pipeline/steps/ package. Each step validates pre-conditions and returns a StepResult that drives subsequent execution.

Rebase Base Mismatch

The rebase step fails with rebase base missing or not fast-forwardable when detectBundledLocalDefaultCommits in internal/pipeline/steps/rebase.go discovers unpushed commits on the default branch that are ancestors of the feature branch. This prevents silent data loss.

Push the missing default-branch work first:

git checkout $(git symbolic-ref --short HEAD)
git push origin HEAD
no-mistakes run

Alternatively, set allow_unpushed_default: true in the repo config to rebase on an older default tip intentionally.

Force-Push Lease Violations

The push step aborts with force-push would discard unseen upstream commits when resolveForcePushDecision in internal/pipeline/steps/forcepush.go detects that the last-seen remote SHA (lastSeenSHA) and base SHA (baseSHA) do not align. If any commit on the remote is not reachable from baseSHA, the lease refuses to push.

Refresh the remote tip and retry:

git fetch origin <branch>
git rebase origin/<branch>
no-mistakes run

When the pipeline performs a true force-push after a CI auto-fix, it calls pushUpdatedHeadSHA which passes Run.BaseSHA as the exclusion set. Do not replace this logic with a plain git push --force.

CI Timeout Configuration

The pipeline terminates with ci timeout reached when the ci_timeout duration expires. The parseCITimeout function in internal/config/config.go interprets values ≤ 0 as CITimeoutUnlimited, while the default is 7 days (config.DefaultCITimeout).

Set unlimited duration in .no-mistakes.yaml:

ci_timeout: "unlimited"

Awaiting Agent Stalls

The axi status command shows awaiting_agent: parked indefinitely when the executor sets Run.AwaitingAgentSince in internal/pipeline/executor.go but never clears it. This occurs when a step hits an approval gate (awaiting_approval or fix_review) and the daemon crashes or the agent fails to respond via axi respond.

Resolve by aborting the stale run:

no-mistakes axi status --run <id>
no-mistakes axi abort --run <id>
no-mistakes daemon restart

The clearing logic lives in executor.go and the database helpers in internal/db/run.go.

Subprocess Leaks and Worktree Management

The daemon hangs and locks the worktree when external commands like npm test spawn orphaned processes. This happens when subprocesses are not wrapped with ConfigureShellCommand in internal/shellenv/shellenv.go.

The helper puts child processes in their own process group and wires the Cancel function to kill the entire tree. When adding custom steps or new agent integrations, replicate the pattern from internal/intent/reader_claude.go to prevent detached-HEAD errors and subprocess leaks.

Summary

• Configuration errors originate from strict unmarshalling in internal/config/config.go; validate YAML structure and types before running.
• Repository trust failures occur when loadTrustedRepoConfig in internal/daemon/manager.go cannot fetch the pinned default-branch SHA; ensure remote connectivity.
• Rebase mismatches are detected by detectBundledLocalDefaultCommits in rebase.go; push default-branch commits before rebasing.
• Force-push violations are prevented by resolveForcePushDecision in forcepush.go; refresh remote refs before pushing.
• CI timeouts default to 7 days but accept "unlimited" via parseCITimeout in config.go.
• Agent stalls require aborting the run via axi abort and restarting the daemon to clear AwaitingAgentSince flags.

Frequently Asked Questions

Why does no-mistakes report "trusted config missing" even when my YAML is valid?

The daemon in internal/daemon/manager.go fetches the default-branch tip and reads the config from the pinned commit SHA, not the working directory. If git fetch fails or the default branch lacks .no-mistakes.yaml, the trusted config is nil. Ensure git rev-parse origin/<branch> succeeds and the file exists at that commit.

How do I fix "rebase base missing or not fast-forwardable" errors?

This error from internal/pipeline/steps/rebase.go indicates the local default branch contains unpushed commits that are ancestors of your feature branch. Push the default branch to origin first, or set allow_unpushed_default: true to proceed with rebasing on an older tip.

What causes CI timeouts and how do I set unlimited duration?

The ci_timeout setting in internal/config/config.go defaults to 7 days. Values ≤ 0 are interpreted as CITimeoutUnlimited. Set ci_timeout: "unlimited" in .no-mistakes.yaml to prevent the pipeline from terminating during long-running CI monitors.

How do I resolve stuck "awaiting_agent" status in no-mistakes?

The executor sets AwaitingAgentSince in internal/pipeline/executor.go when waiting for approval, but clears it only upon agent response or cancellation. Check status with no-mistakes axi status, abort the run with no-mistakes axi abort --run <id>, and restart the daemon to clear stale flags from internal/db/run.go.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}