gastownhall/beads · error

create config.yaml: %w

Error message

create config.yaml: %w

What it means

Wrapped by finalizeSyncedBootstrap in cmd/bd/bootstrap.go:839 after a successful sync clone, when createConfigYaml fails to write the .beads/config.yaml file. This file matches the on-disk layout bd init produces, so bootstrap cannot be finalized without it. The underlying error is a filesystem write failure (permissions, read-only mount, or path problems).

Source

Thrown at cmd/bd/bootstrap.go:839

	case cfg.IsDoltProxiedServerMode():
		cfg.DoltMode = configfile.DoltModeProxiedServer
	case cfg.IsDoltServerMode() || doltserver.IsSharedServerMode():
		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

View on GitHub (pinned to 71377f2769)

Solutions

1. Check permissions on the .beads directory and fix with chown/chmod so the current user can write
2. Remove any stray config.yaml directory (not file) inside .beads
3. Ensure the target filesystem is writable (not mounted read-only, disk not full)
4. Re-run bd bootstrap after fixing; the operation is idempotent

Example fix

// before: .beads owned by root
$ bd bootstrap
// error: create config.yaml: permission denied
// after
$ sudo chown -R $(whoami) .beads
$ bd bootstrap

// before running bd bootstrap
if [ ! -w .beads ]; then echo '.beads not writable'; exit 1; fi
if [ -d .beads/config.yaml ]; then echo 'config.yaml is a directory'; exit 1; fi

err := bdBootstrap(ctx)
if err != nil {
	var pe *fs.PathError
	if errors.As(err, &pe) && errors.Is(pe.Err, os.ErrPermission) {
		// prompt for ownership/permission fix and retry
	}
}

When it happens

Trigger: bd bootstrap (or bd init clone path via executeSyncAction) reaches finalizeSyncedBootstrap on a synced workspace and createConfigYaml fails because the .beads directory is unwritable, config.yaml exists as a directory, or the filesystem is read-only.

Common situations: Cloning into a directory owned by another user; .beads on a read-only NFS/CI mount; a stray config.yaml directory left by a failed run; running under a different UID than the repo owner.

Related errors

• create beads directory: %w
• write metadata.json: %w
• failed to create dolt directory: %w
• failed to create lock file: %w
• dolt path is not executable

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