gastownhall/beads · error

invalid database name %q (use cfg.GetDoltDatabase() to resol

Error message

invalid database name %q (use cfg.GetDoltDatabase() to resolve the configured name): %w

What it means

BootstrapFromRemoteWithDB requires a non-empty database name and validates it with ValidateDatabaseName before cloning. The error means the database argument failed validation (empty, whitespace, or path-like characters). The message hints that callers should resolve the name via cfg.GetDoltDatabase(), which applies the fallback chain env var → config → default ("beads").

Source

Thrown at internal/storage/dolt/bootstrap.go:59

}

// BootstrapFromRemoteWithDB is like BootstrapFromRemote but allows
// specifying the database name (used by the embedded driver for the
// subdirectory structure). The database parameter must not be empty;
// callers should use cfg.GetDoltDatabase() which applies the fallback chain
// (env var → config → default).
func BootstrapFromRemoteWithDB(ctx context.Context, doltDir, remoteURL, database string) (bool, error) {
	// Skip if Dolt database already exists
	if doltExists(doltDir) {
		return false, nil
	}

	if err := remotecache.ValidateRemoteURL(remoteURL); err != nil {
		return false, fmt.Errorf("invalid remote URL: %w", err)
	}

	if err := ValidateDatabaseName(database); err != nil {
		return false, fmt.Errorf("invalid database name %q (use cfg.GetDoltDatabase() to resolve the configured name): %w", database, err)
	}

	// Verify dolt CLI is available
	if _, err := exec.LookPath("dolt"); err != nil {
		return false, fmt.Errorf("dolt CLI not found (required for remote bootstrap): %w", err)
	}

	// Create the parent dolt directory
	if err := os.MkdirAll(doltDir, 0o750); err != nil {
		return false, fmt.Errorf("failed to create dolt directory: %w", err)
	}

	// Clone into <doltDir>/<database>/ so the embedded driver can find it.
	// `dolt clone <url> <target>` creates <target>/.dolt/ directly.
	cloneTarget := filepath.Join(doltDir, database)
	// Record whether the target already existed before this clone attempt.
	// If it did, the failed-clone cleanup below must never touch it: it
	// wasn't created by us, so it could be a pre-existing Dolt repo (e.g.

View on GitHub (pinned to 71377f2769)

Solutions

1. Call bootstrap through the normal path so the database name comes from cfg.GetDoltDatabase() (env var → config → default "beads") instead of passing a raw/unresolved value.
2. If you must pass a name directly, supply a simple identifier (letters/digits/dashes, no slashes or spaces), e.g. "beads".
3. Check .beads/config.yaml and the relevant env var for an empty or whitespace database value and set a valid name.
4. Read the wrapped ValidateDatabaseName error (%w) — it states exactly which rule the name violated.

Example fix

// before
name := os.Getenv("BEADS_DB") // may be empty
bootstrap.BootstrapFromRemoteWithDB(ctx, doltDir, remote, name)
// after
name := cfg.GetDoltDatabase()
bootstrap.BootstrapFromRemoteWithDB(ctx, doltDir, remote, name)

if err := dolt.ValidateDatabaseName(database); err != nil {
    return fmt.Errorf("database name %q invalid: %w", database, err)
}

ok, err := dolt.BootstrapFromRemoteWithDB(ctx, doltDir, remote, db)
if err != nil && strings.Contains(err.Error(), "invalid database name") {
    // fall back to the default chain: cfg.GetDoltDatabase() -> "beads"
    db = cfg.GetDoltDatabase()
}

When it happens

Trigger: Passing "", a whitespace-only string, or a string containing path separators/illegal characters as the database parameter to BootstrapFromRemoteWithDB or BootstrapFromGitRemoteWithDB instead of the resolved value from cfg.GetDoltDatabase().

Common situations: Calling bootstrap from custom tooling with a hardcoded empty database name; a config file where the dolt database key exists but is blank; passing a raw path like ".beads/dolt/beads" instead of just the database name.

Related errors

• database %q not found on Dolt server at %s:%d
• invalid remote URL: %w
• multiple .doltcfg directories detected
• dolt directory is required
• identity: invalid proxy secret

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