gastownhall/beads · error

failed to record the workspace identity: %v

Error message

failed to record the workspace identity: %v

What it means

This error wraps any failure from the workspace-identity bootstrap step during `bd init`. The bootstrapper records the workspace identity (prefix + project ID) in the newly initialized workspace; if that write fails, init aborts with this message and the underlying cause appended via %v.

Source

Thrown at cmd/bd/init.go:319

		// half-bootstrapped state the role refuses to complete later.
		if existing, err := configfile.Load(beadsDir); err == nil && existing != nil {
			projectID = existing.ProjectID
		}
		if projectID == "" {
			projectID = configfile.GenerateProjectID()
		}
	}

	bootstrapper, err := store.Bootstrapper()
	if err != nil {
		return fmt.Errorf("failed to reach the workspace identity: %v", err)
	}
	_, err = bootstrapper.Bootstrap(ctx, issueops.BootstrapRequest{
		Prefix:    prefix,
		ProjectID: projectID,
	})
	if err != nil {
		return fmt.Errorf("failed to record the workspace identity: %v", err)
	}
	return nil
}

var initCmd = &cobra.Command{
	Use:           "init",
	GroupID:       "setup",
	SilenceUsage:  true,
	SilenceErrors: true,
	Short:         "Initialize bd in the current directory",
	Long: `Initialize bd in the current directory by creating a .beads/ directory
and its storage (a Dolt database by default). Optionally specify a custom issue prefix.

Dolt is the default and only supported storage backend, with full version
control (history, branching, sync).

Use --database to specify an existing server database name, overriding the
default prefix-based naming. This is useful when an external tool (e.g. an orchestrator)

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause after 'failed to record the workspace identity:' — it names the real failure
2. Check the .beads data directory permissions and disk space
3. If re-initializing an existing workspace, back up and remove the old identity/state or use matching prefix/project ID values
4. Retry when no other bd process is running (lock contention)

Example fix

// before
bd init  # fails: failed to record the workspace identity: database is locked
// after
# close other bd sessions / remove stale lock, then re-run
bd init

# before init
[ -w .beads ] || { echo 'data dir not writable'; exit 1; }
pgrep -f 'bd ' && echo 'other bd processes may hold locks'

err := bootstrapper.Bootstrap(ctx, req)
if err != nil {
    return fmt.Errorf("failed to record the workspace identity: %w", err)
}
// at CLI boundary: match on the prefix string and print the wrapped cause to the user

When it happens

Trigger: Running `bd init` when bootstrapper.Bootstrap(ctx, issueops.BootstrapRequest{Prefix, ProjectID}) returns an error — e.g. the underlying database write fails, the workspace identity record already exists with conflicting values, or storage is unreachable/locked.

Common situations: Initializing a workspace in a directory with a corrupt or partially-created .beads database; permission problems on the data directory; concurrent bd processes holding a lock during init; re-running init over an existing workspace with a different prefix/project ID.

Related errors

• commit import: %w
• failed to set routing.contributor: %w
• failed to set sync branch: %w
• no store is open for this workspace
• not found

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