gastownhall/beads · error

failed to reach the workspace identity: %v

Error message

failed to reach the workspace identity: %v

What it means

seedInitWorkspaceIdentity records the workspace identity (prefix + project id) during init via the store's Bootstrapper. If obtaining the Bootstrapper itself fails (store.Bootstrapper() error), init reports it as 'failed to reach the workspace identity' — the identity write never started.

Source

Thrown at cmd/bd/init.go:312

		warnHalfIdentifiedSubstrate(found)
		return nil
	}
	if projectID == "" {
		// No metadata.json was composed on this path. Take the id the workspace
		// already records so the substrate and the file agree, and mint one only
		// when neither exists: a prefix without an identity is the
		// 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

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the %v cause and check the Dolt server/connection state (`bd doctor`)
2. Retry `bd init` if the cause is transient (network blip)
3. Verify gateway credentials and hosted-server availability if in gateway mode
4. Check DB health/locks and storage-driver compatibility (bd version vs server version)

// Confirm the store is open and reachable before init proceeds
if err := store.Ping(ctx); err != nil {
    return fmt.Errorf("store unreachable before identity seeding: %w", err)
}

bootstrapper, err := store.Bootstrapper()
if err != nil {
    // transient connection issues: retry once, then surface
    if isTransient(err) {
        time.Sleep(time.Second)
        bootstrapper, err = store.Bootstrapper()
    }
    if err != nil { return fmt.Errorf("failed to reach the workspace identity: %v", err) }
}

When it happens

Trigger: `bd init` on an unidentified substrate (no prefix and no project id found) where store.Bootstrapper() returns an error: DB connection lost/closed, Dolt server unreachable, gateway connection failure, or the storage driver not supporting the bootstrapper seam.

Common situations: Dolt server stopped between the DB open and this call; gateway network/auth failure mid-init; corrupt or locked database; version mismatch where the driver lacks Bootstrapper support.

Related errors

• dolt server connection failed: %w
• begin tx: %w
• begin read tx: %w
• begin write tx: %w
• acquire connection after SQL mutation: %w: %w

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