gastownhall/beads · error

ensure .beads/.gitignore: %w

Error message

ensure .beads/.gitignore: %w

What it means

Wrapped by finalizeSyncedBootstrap in cmd/bd/bootstrap.go:842 when doctor.EnsureGitignoreForBeadsDir fails to create/ensure .beads/.gitignore. This step keeps Dolt data files out of git; bootstrap aborts so the workspace is not left committing database files. The wrapped error is a filesystem write failure.

Source

Thrown at cmd/bd/bootstrap.go:842

		cfg.DoltMode = configfile.DoltModeServer
	default:
		cfg.DoltMode = configfile.DoltModeEmbedded
	}
	// Mirror init's convention: metadata.json database points at the Dolt
	// directory rather than the legacy "beads.db" placeholder.
	if cfg.Database == "" || cfg.Database == beads.CanonicalDatabaseName {
		cfg.Database = "dolt"
	}

	if err := cfg.Save(beadsDir); err != nil {
		return fmt.Errorf("write metadata.json: %w", err)
	}

	if err := createConfigYaml(beadsDir, false, ""); err != nil {
		return fmt.Errorf("create config.yaml: %w", err)
	}
	if err := doctor.EnsureGitignoreForBeadsDir(beadsDir); err != nil {
		return fmt.Errorf("ensure .beads/.gitignore: %w", err)
	}

	// Persist sync.remote so subsequent fresh clones (and bd bootstrap
	// retries) can rediscover the remote without re-probing origin refs.
	if syncRemote != "" {
		if err := config.SetYamlConfigInDir(beadsDir, "sync.remote", syncRemote); err != nil {
			return fmt.Errorf("persist sync.remote to config.yaml: %w", err)
		}
	}

	return nil
}

type remoteCloneMode int

const (
	remoteCloneAuto remoteCloneMode = iota
	remoteCloneEmbedded

View on GitHub (pinned to 71377f2769)

Solutions

1. Make .beads writable by the current user (chown/chmod)
2. Check for a .gitignore entry that is a directory and remove it
3. Verify the mount is writable and the disk is not full
4. Re-run bd bootstrap; finalize is idempotent

Example fix

// before
$ bd bootstrap
// error: ensure .beads/.gitignore: permission denied
// after
$ chmod u+w .beads && rm -rf .beads/.gitignore.bak
$ bd bootstrap

if [ ! -w .beads ]; then echo '.beads not writable by current user'; exit 1; fi

if err := finalize(); err != nil {
	if strings.Contains(err.Error(), "ensure .beads/.gitignore") {
		// inspect and fix .beads permissions, then retry
	}
}

When it happens

Trigger: bd bootstrap finishes cloning and calls EnsureGitignoreForBeadsDir, which fails because the .beads directory is read-only, owned by another user, or a .gitignore path exists as a directory.

Common situations: Same permission/mount issues as other finalize steps; enterprise machines with group-writable restrictions; CI containers with a read-only workspace; disk-quota exhaustion.

Related errors

• read .beads/.gitignore: %w
• failed to read .gitignore: %w
• failed to write .gitignore: %w
• fs: WriteBeadsGitignore: %w
• fs: WriteBeadsGitignore: read: %w

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