What causes "server: DoltServer.Start: resolve proxy root identity: %w" in gastownhall/beads?

Verify rootDir is an initialized dolt repo (contains .dolt); if not, delete the stale dir and let beads re-initialize.

server: DoltServer.Start: resolve proxy root identity: %w

Error message

server: DoltServer.Start: resolve proxy root identity: %w

What it means

Start() could not resolve the proxy root identity for the server's root directory via identity.RootID. This identity is embedded in the pidfile so other processes can verify they are talking to a server managing the same data root. The child process is killed and start state rolled back.

Source

Thrown at internal/storage/dbproxy/server/doltserver.go:285

	s.pid = cmd.Process.Pid
	birth, err := procid.Capture(s.pid)
	if err != nil {
		_ = cmd.Process.Kill()
		_, _ = cmd.Process.Wait()
		s.eg, s.egCtx, s.cancel, s.pid = nil, nil, nil, 0
		cancel()
		lock.Unlock()
		return fmt.Errorf("server: DoltServer.Start: capture child birth identity: %w", err)
	}
	rootID, err := identity.RootID(s.rootDir)
	if err != nil {
		_ = cmd.Process.Kill()
		_, _ = cmd.Process.Wait()
		s.eg, s.egCtx, s.cancel, s.pid = nil, nil, nil, 0
		cancel()
		lock.Unlock()
		return fmt.Errorf("server: DoltServer.Start: resolve proxy root identity: %w", err)
	}

	if err := pidfile.Write(s.rootDir, PIDFileName, pidfile.PidFile{
		Pid:    s.pid,
		Port:   s.config.Port(),
		Schema: pidfile.SchemaV2,
		Kind:   pidfile.KindDoltBackend,
		Birth:  string(birth),
		RootID: rootID,
	}); err != nil {
		_ = cmd.Process.Kill()
		_, _ = cmd.Process.Wait()
		s.eg, s.egCtx, s.cancel, s.pid = nil, nil, nil, 0
		cancel()
		lock.Unlock()
		return fmt.Errorf("server: DoltServer.Start: write pidfile: %w", err)
	}

View on GitHub (pinned to 71377f2769)

Solutions

Verify rootDir is an initialized dolt repo (contains .dolt); if not, delete the stale dir and let beads re-initialize.
Check permissions on rootDir and its metadata files.
If identity metadata is corrupt, restore from backup or re-init the repository.
Confirm the same rootDir is used consistently by all processes accessing this storage.

Defensive patterns

Strategy: validation

Validate before calling

// rootDir must exist and contain dolt metadata before Start.
if _, err := os.Stat(filepath.Join(rootDir, ".dolt")); err != nil {
    return fmt.Errorf("rootDir %s is not an initialized dolt repository: %w", rootDir, err)
}
if !isDirWritable(rootDir) {
    return fmt.Errorf("rootDir %s is not writable", rootDir)
}

Try / catch

if err := srv.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "resolve proxy root identity") {
        return fmt.Errorf("storage root %s identity unreadable/corrupt: %w", rootDir, err)
    }
    return err
}

Prevention

Never delete or recreate rootDir while a server manages it.
Keep data dirs on stable local storage; avoid concurrent modification by other tools.
Use the same beads/dolt version across all processes sharing a data dir.
Back up rootDir before version migrations.

When it happens

Trigger: identity.RootID(s.rootDir) fails after the child spawned — typically because rootDir is not a valid/initialized dolt repository or the identity metadata files are missing/corrupt/unreadable.

Common situations: Pointing the server at a directory that was deleted or re-created between init and start; corruption of the dolt repo metadata; permission changes on the data dir; mixing versions whose identity format differs.

Related errors

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