gastownhall/beads · critical

failed to load %s: %w; refusing to reinitialize automaticall

Error message

failed to load %s: %w; refusing to reinitialize automatically (restore the metadata or use --reinit-local after safeguarding existing data)

What it means

checkExistingBeadsDataAt loads .beads/metadata.json (via configfile.LoadForDiscovery) to determine the configured backend before deciding whether init may proceed. If the metadata is unreadable or corrupt, init fails closed instead of silently reinitializing a fresh embedded Dolt DB — which would orphan the issues of an external/nonlocal database whose only local marker is that metadata file. The error wraps the load failure and explicitly points at --reinit-local as the override.

Source

Thrown at cmd/bd/init.go:2463

// operational and must not be treated as success.

func checkExistingBeadsDataAt(beadsDir string, prefix string) error {
	// Check if .beads directory exists
	if _, err := os.Stat(beadsDir); os.IsNotExist(err) {
		return nil // No .beads directory, safe to init
	}

	// metadata.json is authoritative for the configured backend, so resolve it once
	// and dispatch. Removed-backend tombstones are marked by metadata
	// alone — there is no local Dolt directory to inspect — so a plain
	// `bd init` (which defaults to Dolt) must not silently repoint a live SQL
	// workspace to a fresh embedded Dolt DB and orphan its issues. --reinit-local
	// /--force bypass this (handled by the caller). Invalid metadata must fail closed:
	// without an explicit reinitialization request, init may not overwrite the only
	// marker for an external or otherwise nonlocal database.
	cfg, cfgErr := configfile.LoadForDiscovery(beadsDir)
	if cfgErr != nil {
		return fmt.Errorf("failed to load %s: %w; refusing to reinitialize automatically (restore the metadata or use --reinit-local after safeguarding existing data)", configfile.ConfigPath(beadsDir), cfgErr)
	}
	if cfg != nil {
		if guardErr := validateConfiguredBackend(cfg); guardErr != nil {
			return guardErr
		}
	}

	if cfg != nil && cfg.GetBackend() == configfile.BackendDolt {
		if cfg.IsDoltProxiedServerMode() {
			proxiedRoot, rootErr := resolveProxiedServerRootPath(beadsDir)
			if rootErr != nil {
				return fmt.Errorf("resolve proxied server root: %w", rootErr)
			}
			if info, statErr := os.Stat(proxiedRoot); statErr == nil && info.IsDir() {
				return alreadyInitialized(`
%s Found existing Dolt database: %s

This workspace is already initialized.

View on GitHub (pinned to 71377f2769)

Solutions

1. Restore valid metadata: git checkout .beads/metadata.json (or restore from backup) so bd can discover the configured backend, then re-run bd init.
2. Validate and hand-repair the JSON (jq . .beads/metadata.json) — fix syntax and ensure the backend field is a supported value.
3. If the local data is disposable or already safeguarded (backed up, external DB verified reachable), deliberately reinitialize with bd init --reinit-local (or --force).
4. If the workspace actually points at an external/proxied database, fix connectivity/config so the external database is used instead of reinitializing locally.

Example fix

// before: corrupt metadata
$ bd init
# failed to load .beads/metadata.json: unexpected end of JSON input; refusing to reinitialize automatically...

// after: restore from git, then init
$ git checkout -- .beads/metadata.json
$ bd init  # discovers existing backend, aborts with 'already initialized' or proceeds safely

// Preflight: verify metadata parses before invoking init paths
raw, err := os.ReadFile(filepath.Join(beadsDir, "metadata.json"))
if err != nil && !os.IsNotExist(err) {
    return fmt.Errorf("metadata unreadable: %w", err)
}
if raw != nil {
    if err := json.Valid(raw); !err {
        return fmt.Errorf(".beads/metadata.json is not valid JSON; restore it before init")
    }
}

if err := checkExistingBeadsData(); err != nil {
    if errors.Is(err, errWorkspaceAlreadyInitialized) {
        return nil // benign skip
    }
    if strings.Contains(err.Error(), "refusing to reinitialize automatically") {
        // corrupt metadata: require explicit operator action (--reinit-local) or restore
        return err
    }
    return err
}

When it happens

Trigger: Running `bd init` (or --init-if-missing, or the check via checkExistingBeadsData) in a workspace where a .beads directory exists but configfile.LoadForDiscovery(beadsDir) returns an error — corrupt/invalid JSON in .beads/metadata.json, invalid schema fields, or an unreadable metadata file.

Common situations: A partially completed init or crash left truncated metadata.json; manual editing introduced invalid JSON or unknown backend values; a merge conflict in metadata.json was resolved badly; file permissions make metadata unreadable; upgrading from an old bd version whose metadata format no longer parses.

Related errors

• failed to persist sync.remote to config.yaml: %v
• failed to set beads.role config: %w
• failed to set routing.contributor: %w
• failed to set sync.remote: %w
• record repo_id: %w

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