What causes "%s" in gastownhall/beads?

Run bd init in the repository to create the .beads workspace

%s

Error message

%s

What it means

pushStatePath returns this error when beads.FindBeadsDir() cannot locate a .beads directory for the current workspace. The Dolt auto-push feature needs a place to store push-state.json, and without a beads workspace there is nowhere to put it. The message text comes from activeWorkspaceNotFoundError(), so the actual explanation is the workspace-not-found family.

Source

Thrown at cmd/bd/dolt_autopush.go:33

)

// pushState tracks auto-push state in a local file (.beads/push-state.json)
// instead of the Dolt metadata table, to avoid merge conflicts on multi-machine
// setups (GH#2466).
type pushState struct {
	LastPush   string `json:"last_push"`   // RFC3339 timestamp
	LastCommit string `json:"last_commit"` // Dolt commit hash
}

type autoPushTarget interface {
	GetCurrentCommit(ctx context.Context) (string, error)
	Push(ctx context.Context) error
}

func pushStatePath() (string, error) {
	beadsDir := beads.FindBeadsDir()
	if beadsDir == "" {
		return "", fmt.Errorf("%s", activeWorkspaceNotFoundError())
	}
	return filepath.Join(beadsDir, "push-state.json"), nil
}

func loadPushState() (*pushState, error) {
	path, err := pushStatePath()
	if err != nil {
		return nil, err
	}
	data, err := os.ReadFile(path) //nolint:gosec // path is constructed internally
	if os.IsNotExist(err) {
		return nil, nil
	}
	if err != nil {
		return nil, err
	}
	var ps pushState
	if err := json.Unmarshal(data, &ps); err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

Run bd init in the repository to create the .beads workspace
cd into the repository root (or a subdirectory of it) so FindBeadsDir can walk up to .beads
Set the beads directory env override explicitly if the workspace lives elsewhere

Example fix

// before (run in ~/tmp, no .beads)
bd push
// after
cd ~/my-repo && bd init && bd push

Defensive patterns

Strategy: validation

Validate before calling

if beads.FindBeadsDir() == "" {
    return errors.New("not in a beads workspace: run 'bd init'")
}

Try / catch

path, err := pushStatePath()
if err != nil {
    return fmt.Errorf("cannot persist push state (run bd init first): %w", err)
}

Prevention

Always run bd init after cloning a repository
Run bd commands from inside the repo so FindBeadsDir can walk up to .beads
In CI, assert the .beads directory exists before invoking push-dependent commands

When it happens

Trigger: Running a command that triggers loadPushState/savePushState (auto-push) outside any directory hierarchy containing a .beads directory, or when BD_* env overrides point at a missing location.

Common situations: Running bd from a fresh clone without bd init; running from an unrelated directory with the wrong cwd; CI job checking out only part of the repo so .beads is absent.

Related errors

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