gastownhall/beads · error

resolve backend root identity: %w

Error message

resolve backend root identity: %w

What it means

After the backend record validates, cleanup compares the record's RootID against the workspace's current root identity (identity.RootID(rootDir)). This error wraps a failure to compute that workspace identity — cleanup cannot safely proceed without it, so it aborts before touching any process.

Source

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

			}
			return nil
		}
		if probeErr != nil {
			err = errors.Join(err, fmt.Errorf("probe recorded pid: %w", probeErr))
		}
		return unverifiableProcessError(
			"backend cleanup",
			recordPath,
			pf.Pid,
			err,
			unverifiableProcessChecks{
				LiveEstablished: live,
			},
		)
	}
	expectedRootID, err := identity.RootID(rootDir)
	if err != nil {
		return fmt.Errorf("resolve backend root identity: %w", err)
	}
	if pf.RootID != expectedRootID {
		return unverifiableProcessError(
			"backend cleanup",
			recordPath,
			pf.Pid,
			fmt.Errorf("root identity mismatch (record has %q, workspace has %q)", pf.RootID, expectedRootID),
			unverifiableProcessChecks{},
		)
	}

	handle, dead, err := openRecordedProcess(pf)
	if err != nil {
		return unverifiableProcessError(
			"backend cleanup",
			recordPath,
			pf.Pid,
			err,

View on GitHub (pinned to 71377f2769)

Solutions

1. Run bd from the workspace root and verify the workspace is initialized (bd doctor).
2. Restore or re-create the missing workspace root metadata; if the workspace is disposable, re-init it.
3. Check read permissions on the workspace root identity file and fix them.
4. Verify the path/rootDir configuration points at the intended workspace.

Example fix

// before
Error: resolve backend root identity: open /ws/.beads/root-id: no such file or directory
// after
$ cd /ws && bd doctor   # or re-init the workspace to restore root metadata

if _, err := identity.RootID(rootDir); err != nil {
    return fmt.Errorf("workspace root identity missing/corrupt, run bd doctor or re-init: %w", err)
}

if err := cleanupOrphanBackend(rootDir); err != nil && strings.Contains(err.Error(), "resolve backend root identity") {
    // recover by re-initializing workspace metadata, then retry
    _ = reinitWorkspaceMetadata(rootDir)
    err = cleanupOrphanBackend(rootDir)
}

When it happens

Trigger: identity.RootID(rootDir) returns an error during cleanupOrphanBackend at internal/storage/dbproxy/proxy/endpoint.go:805-807 — typically the workspace root metadata needed to derive the identity is missing or unreadable.

Common situations: Running the command outside a properly initialized bd workspace; the workspace root metadata file was deleted or corrupted; wrong rootDir passed (e.g. running from a subdirectory with a misconfigured path); permissions on the root identity file.

Related errors

• resolve workspace identity: %w
• dolt path is not executable
• server: NewDoltServer: failed to determine absolute path of
• server: NewDoltServer: failed to determine absolute path of
• server: NewDoltServer: failed to determine absolute path of

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