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

> Resolve common no-mistakes errors affecting configuration parsing, repository trust, and pipeline pre-conditions. Learn troubleshooting steps for your Go CLI.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: how-to-guide
- Published: 2026-06-28

---

**Most runtime failures in `no-mistakes` stem from three subsystems: strict configuration parsing in [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go), repository trust validation in [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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:

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go) fails to fetch the default-branch tip and resolve the exact commit SHA. The system reads [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.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:

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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:

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/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:

```bash
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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go) interprets values ≤ 0 as `CITimeoutUnlimited`, while the default is 7 days (`config.DefaultCITimeout`).

Set unlimited duration in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml):

```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`](https://github.com/kunchenguid/no-mistakes/blob/main/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:

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

```

The clearing logic lives in [`executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/executor.go) and the database helpers in [`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go); validate YAML structure and types before running.
- **Repository trust failures** occur when `loadTrustedRepoConfig` in [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go) cannot fetch the pinned default-branch SHA; ensure remote connectivity.
- **Rebase mismatches** are detected by `detectBundledLocalDefaultCommits` in [`rebase.go`](https://github.com/kunchenguid/no-mistakes/blob/main/rebase.go); push default-branch commits before rebasing.
- **Force-push violations** are prevented by `resolveForcePushDecision` in [`forcepush.go`](https://github.com/kunchenguid/no-mistakes/blob/main/forcepush.go); refresh remote refs before pushing.
- **CI timeouts** default to 7 days but accept `"unlimited"` via `parseCITimeout` in [`config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/.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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go) defaults to 7 days. Values ≤ 0 are interpreted as `CITimeoutUnlimited`. Set `ci_timeout: "unlimited"` in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go).