What causes "locate bd executable: %w" in gastownhall/beads?

Reinstall or restore the bd binary at its expected location and retry.

locate bd executable: %w

Error message

locate bd executable: %w

What it means

Returned by forkExecChild when ResolveExecutable cannot locate the bd executable needed to re-exec itself as the db-proxy child. The proxy spawn mechanism re-invokes the same binary (`bd db-proxy-child`), so if the running binary's path can't be resolved, the spawn fails before any process is created.

Source

Thrown at internal/storage/dbproxy/proxy/endpoint.go:435

type spawnedProxyChild struct {
	cmd    *exec.Cmd
	done   <-chan error
	handle *procid.Handle
	marker spawnMarker
}

func forkExecChild(rootDir string, opts OpenOpts, port int, stopEpoch string, lock *util.Lock) (*spawnedProxyChild, error) {
	released := false
	defer func() {
		if !released {
			lock.Unlock()
		}
	}()

	self, err := ResolveExecutable()
	if err != nil {
		return nil, fmt.Errorf("locate bd executable: %w", err)
	}

	idleTimeout := opts.IdleTimeout
	if idleTimeout < 0 {
		idleTimeout = IdleTimeoutNever
	}

	args := []string{
		"db-proxy-child",
		"--root", rootDir,
		"--port", strconv.Itoa(port),
		"--idle-timeout", idleTimeout.String(),
		"--backend", string(opts.Backend),
		"--stop-epoch", stopEpoch,
	}
	if opts.ConfigFilePath != "" {
		args = append(args, "--config", opts.ConfigFilePath)
	}

View on GitHub (pinned to 71377f2769)

Solutions

Reinstall or restore the bd binary at its expected location and retry.
Run bd from a stable installed path (not a temp file or ephemeral symlink).
Check the wrapped error from ResolveExecutable for the specific lookup failure (os.Executable error vs missing file).
In containers, bake bd into the image at a fixed path and invoke it via that path.

Example fix

// before: running from a throwaway path
/tmp/download/bd doctor  # later spawns fail: binary gone
// after: install to a stable location first
cp -f /tmp/download/bd /usr/local/bin/bd && /usr/local/bin/bd doctor

Defensive patterns

Strategy: validation

Validate before calling

self, err := os.Executable()
if err != nil { return err }
if _, err := os.Stat(self); err != nil { return fmt.Errorf("bd binary missing at %s: %w", self, err) }

Try / catch

ep, err := GetCreateDatabaseProxyServerEndpoint(rootDir, opts)
if err != nil && strings.Contains(err.Error(), "locate bd executable") {
    return fmt.Errorf("bd binary moved/deleted; reinstall and retry: %w", err)
}

Prevention

Never delete/replace the running bd binary mid-session; install new versions atomically afterward
Run bd from a stable installed path, not temp dirs or transient symlinks
In containers, bake bd into the image at a fixed path
Don't invoke bd through symlinks that may be removed

When it happens

Trigger: forkExecChild (via spawnAndHandoff → GetCreateDatabaseProxyServerEndpoint) runs when the bd binary has been deleted/moved after start, os.Executable fails, the binary was invoked through a symlink since removed, or in odd environments (tmpfs-cleared paths, containers).

Common situations: Upgrading/replacing the bd binary while a command is running; running bd from a deleted temp download; invoking through a transient symlink; container images where the binary path differs between build and runtime.

Related errors

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