gastownhall/beads · error

failed to initialize remote cache: %w

Error message

failed to initialize remote cache: %w

What it means

This error is returned by openDryRunTargetStore in cmd/bd/create.go when `bd create --dry-run --repo <remote-url>` targets a remote URL but remotecache.DefaultCache() fails to initialize the local cache of remote Dolt databases. It wraps the underlying cause with %w so the real failure (cache dir creation, Dolt config, credentials) is preserved. The dry-run path must read the parent issue from a cached remote store without mutating it, and that cache could not be set up.

Source

Thrown at cmd/bd/create.go:972

	}
	return t.Format(time.RFC3339)
}

// openDryRunTargetStore opens the store a `create --dry-run --repo <other>`
// resolves --parent against. It is read-only on BOTH paths and must stay that
// way: newDoltStoreFromConfig runs schema initialization on whatever it opens
// and can rename a legacy hyphenated database and rewrite the target's
// metadata.json on the way (GH#3231), so using it here would have a dry-run
// mutate a repository the user only named as a lookup target — the same
// migrate-at-open trap this preview policy exists to close, one repo over.
// newPreviewStoreFromConfig is the non-mutating factory for a foreign
// project (bd-6dnrw.32), relaxed for previews exactly as the root pre-run
// relaxes the command's own store.
func openDryRunTargetStore(ctx context.Context, repoPath string) (storage.DoltStorage, error) {
	if remotecache.IsRemoteURL(repoPath) {
		cache, err := remotecache.DefaultCache()
		if err != nil {
			return nil, fmt.Errorf("failed to initialize remote cache: %w", err)
		}
		// The dry-run parent lookup only reads from this cached remote store.
		// Do not add writes here; dry-runs must not mutate cached remotes.
		store, err := cache.OpenStore(ctx, repoPath, newPreviewStoreFromConfig)
		if err != nil {
			return nil, fmt.Errorf("dry-run parent lookup requires an existing cached remote store for %s: %w", repoPath, err)
		}
		return store, nil
	}

	targetPath := routing.ExpandPath(repoPath)
	beadsDir := filepath.Join(targetPath, ".beads")
	metadataPath := filepath.Join(beadsDir, "metadata.json")
	if _, err := os.Stat(metadataPath); err != nil {
		if os.IsNotExist(err) {
			return nil, fmt.Errorf("target repo %s is not initialized; refusing to initialize it during dry-run", targetPath)
		}
		return nil, fmt.Errorf("failed to inspect target repo %s: %w", targetPath, err)

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause (%w) in the error chain to see why DefaultCache() failed and fix that root cause (permissions, disk space, corrupt cache dir).
2. Run a non-dry-run `bd pull` or sync once to warm/populate the remote cache, then retry the dry-run.
3. Verify HOME and the beads config directory are writable and Dolt is correctly installed/configured.
4. If the target is actually local, pass a filesystem path instead of a remote URL so the non-remote branch of openDryRunTargetStore is used.
5. As a last resort, remove the corrupted remote cache directory so it is rebuilt on the next call.

Example fix

// before: dry-run against a remote with no initialized cache
bd create --dry-run "Fix flake" --repo dolt://remote/db
// after: warm the cache first, then dry-run
bd dolt pull
cd example && bd create --dry-run "Fix flake" --repo dolt://remote/db

// Before a remote-URL dry-run, ensure Dolt and the beads config dir are usable.
if remotecache.IsRemoteURL(repoPath) {
    if _, err := exec.LookPath("dolt"); err != nil {
        return fmt.Errorf("dolt not installed; cannot dry-run against remote %s", repoPath)
    }
    if d, err := os.UserHomeDir(); err != nil || d == "" {
        return fmt.Errorf("HOME not set; remote cache unavailable")
    }
}

func isRemoteTarget(repoPath string) bool { return remotecache.IsRemoteURL(repoPath) }

store, err := openDryRunTargetStore(ctx, repoPath)
if err != nil {
    if strings.Contains(err.Error(), "failed to initialize remote cache") {
        var cause error
        if errors.As(err, &cause) || true { /* inspect %w chain */ }
        fmt.Fprintf(os.Stderr, "remote cache unusable: %v\nRun `bd dolt pull` or fix cache dir permissions.\n", err)
        os.Exit(1)
    }
    return err
}

When it happens

Trigger: Calling bd create with --dry-run where the --repo value passes remotecache.IsRemoteURL() (a remote URL, not a filesystem path) and the environment cannot initialize the default remote cache: e.g. the Dolt data dir cannot be created or opened, DoltGlobalSettings/config fails, or the remote-cache credentials/config are missing or corrupt.

Common situations: Running dry-run against a remote repo on a fresh machine or CI container where no remote cache has been pulled yet; read-only or missing HOME directory preventing cache-dir creation; corrupted ~/.beads remote cache state; restricted filesystem permissions.

Related errors

• dry-run parent lookup requires an existing cached remote sto
• failed to open target store for dry-run: %w
• target repo %s is not initialized; refusing to initialize it
• failed to inspect target repo %s: %w
• invalid --dolt-auto-commit=%q (valid: off, on, batch)

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