gastownhall/beads · error

checking source sidecar %s: %w

Error message

checking source sidecar %s: %w

What it means

validateRetireCollisionPolicy checks each retire op: if the source sidecar still exists, its content is compared to the destination before retiring. This error wraps a failure of pathExists(op.SourcePath) itself — i.e. the existence check could not be performed (I/O or permission error on the parent directory), so the collision policy cannot be evaluated safely.

Source

Thrown at cmd/bd/migrate_hooks_apply.go:352

func ensureHookShebang(content string) string {
	if strings.HasPrefix(content, "#!") {
		return content
	}

	trimmedLeading := strings.TrimLeft(content, "\n")
	if trimmedLeading == "" {
		return "#!/usr/bin/env sh\n"
	}

	return "#!/usr/bin/env sh\n" + trimmedLeading
}

func validateRetireCollisionPolicy(retireOps []hookMigrationRetireOp) error {
	for _, op := range retireOps {
		sourceExists, err := pathExists(op.SourcePath)
		if err != nil {
			return fmt.Errorf("checking source sidecar %s: %w", op.SourcePath, err)
		}
		if !sourceExists {
			continue
		}

		destinationExists, err := pathExists(op.DestinationPath)
		if err != nil {
			return fmt.Errorf("checking destination sidecar %s: %w", op.DestinationPath, err)
		}
		if !destinationExists {
			continue
		}

		equal, err := filesEqual(op.SourcePath, op.DestinationPath)
		if err != nil {
			return fmt.Errorf("comparing sidecars %s and %s: %w", op.SourcePath, op.DestinationPath, err)
		}
		if !equal {

View on GitHub (pinned to 71377f2769)

Solutions

1. Check permissions on the hooks directory (`ls -la .git/hooks`, ensure +r/+x for the user)
2. Verify the filesystem is healthy and mounted read-write
3. Re-run apply after fixing access; the check is conservative and will pass once stat succeeds
4. If a concurrent process is mutating the directory, pause it during migration

// verify the directory is stat-able before applying
fs.accessSync(hooksDir, fs.constants.R_OK | fs.constants.X_OK);

if err := apply(...); err != nil && strings.Contains(err.Error(), "checking source sidecar") {
    // fix directory permissions/mount per the wrapped error, then retry
}

When it happens

Trigger: pathExists returned a non-nil error (not merely 'false') while checking op.SourcePath during applyHookMigrationExecution — e.g. unreadable parent directory, broken mount, or EACCES on stat.

Common situations: Hooks directory with restrictive permissions; network/readonly filesystems where stat fails; path removed mid-run by a concurrent process.

Related errors

• failed to stat %s: %w
• writing migrated hook %s: %w
• ensureProxiedServerConfig: stat %s: %w
• failed to stat user config.yaml: %w
• checking dolt metadata directory %s: %w

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