gastownhall/beads · error

unexpected porcelain status record %q

Error message

unexpected porcelain status record %q

What it means

bd parses raw `git status --porcelain=v1 -z` output when fingerprinting target changes. Each record must be at least 4 bytes with a space at offset 2 (`XY path`). This error means git returned a record in an unexpected format, so bd refuses to guess and aborts the fingerprint — usually a git version/behavior mismatch or corrupted capture of the status output.

Source

Thrown at cmd/bd/worktree_cmd.go:1130

		_, err = hasher.Write([]byte{0})
		return err
	})
	if err != nil {
		return "", err
	}
	return fmt.Sprintf("%x", hasher.Sum(nil)), nil
}

func fingerprintWorktreeStatusPaths(worktreePath, status string) (string, error) {
	records := strings.Split(status, "\x00")
	pathSet := make(map[string]struct{})
	for index := 0; index < len(records); index++ {
		record := records[index]
		if record == "" {
			continue
		}
		if len(record) < 4 || record[2] != ' ' {
			return "", fmt.Errorf("unexpected porcelain status record %q", record)
		}
		code := record[:2]
		pathSet[record[3:]] = struct{}{}
		if strings.ContainsAny(code, "RC") {
			index++
			if index >= len(records) || records[index] == "" {
				return "", fmt.Errorf("missing source path for porcelain rename/copy record %q", record)
			}
			pathSet[records[index]] = struct{}{}
		}
	}

	paths := make([]string, 0, len(pathSet))
	for path := range pathSet {
		paths = append(paths, path)
	}
	sort.Strings(paths)

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `git version` and `git -C <worktree> status --porcelain=v1 -z` and inspect raw records (e.g. pipe through `od -c`) to spot the malformed line
2. Upgrade (or downgrade) git to a mainstream release ≥2.x so porcelain v1 -z output matches expectations
3. Report the exact record text to bd maintainers if git's output looks standard — the parser may need updating

Example fix

// inspect raw records
git -C ../mywt status --porcelain=v1 -z | od -c | head
// upgrade git
brew upgrade git  # or apt-get install -y git

out, err := exec.Command("git", "-C", wt, "status", "--porcelain=v1", "-z").Output()
if err != nil || strings.Count(string(out), "\x00") == 0 {
    return fmt.Errorf("status output missing or suspicious")
}

if strings.Contains(err.Error(), "unexpected porcelain status record") {
    // dump raw status via od -c, check git version, report upstream
    t := "git -C <wt> status --porcelain=v1 -z | od -c"
}

When it happens

Trigger: fingerprintWorktreeStatusPaths encountering a -z status record shorter than 4 chars or with a byte other than ' ' at index 2 — e.g. a very new git emitting newer porcelain fields, or output corruption (NUL handling bug, interleaved output).

Common situations: Extremely old or patched/newer git builds diverging from porcelain v1; running against a git shim/wrapper that mangles output; unexpected quote handling around exotic filenames in custom git builds.

Related errors

• missing source path for porcelain rename/copy record %q
• unexpected git rev-parse output
• dolt version output is unparseable
• parsing batch input: %w
• line %d: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/3e3e19e812899a3f. Report an issue: GitHub.