gastownhall/beads · error

embeddeddolt: creating database: %w

Error message

embeddeddolt: creating database: %w

What it means

Wraps the SQL error from 'CREATE DATABASE IF NOT EXISTS `<db>`' during initSchema. The database name has already passed validIdentifier validation (alphanumeric/underscore check), so failures here come from the engine refusing the DDL — engine-level errors, connection lost, or context cancellation. It means the embedded Dolt engine is running but cannot materialize the configured database.

Source

Thrown at internal/storage/embeddeddolt/store.go:331

	}
	defer func() { _ = cleanup() }()

	conn, err := db.Conn(ctx)
	if err != nil {
		return fmt.Errorf("embeddeddolt: pin connection: %w", err)
	}
	defer conn.Close()

	if s.database != "" {
		if !validIdentifier.MatchString(s.database) {
			msg := fmt.Sprintf("embeddeddolt: invalid database name: %q", s.database)
			if strings.ContainsRune(s.database, '-') {
				msg += "; hyphens are not allowed in embedded mode — replace with underscores in .beads/metadata.json dolt_database field, or run 'bd doctor'"
			}
			return errors.New(msg)
		}
		if _, err := conn.ExecContext(ctx, "CREATE DATABASE IF NOT EXISTS `"+s.database+"`"); err != nil {
			return fmt.Errorf("embeddeddolt: creating database: %w", err)
		}
		if _, err := conn.ExecContext(ctx, "USE `"+s.database+"`"); err != nil {
			return fmt.Errorf("embeddeddolt: switching to database: %w", err)
		}
		if s.branch != "" {
			if _, err := conn.ExecContext(ctx, fmt.Sprintf("SET @@%s_head_ref = %s", s.database, sqlStringLiteral(s.branch))); err != nil {
				return fmt.Errorf("embeddeddolt: setting branch: %w", err)
			}
		}
	}

	// Forward-drift guard: if this database's schema is AHEAD of the binary,
	// fail fast with a clear "upgrade bd" message before MigrateUp no-ops and a
	// later query dies on a dropped/renamed column. Embedded mode is the mode
	// the stale-binary incident (#4135/#4137) was observed in. The read-only
	// embedded open (OpenReadOnly) already guards this; the writable open did
	// not. Runs after the USE switch so the version read resolves against the
	// target database.

View on GitHub (pinned to 71377f2769)

Solutions

1. Re-run the command — a partial previous init often left inconsistent state; 'bd doctor' can verify it.
2. Check the dolt_database value in .beads/metadata.json is a plain identifier (letters, digits, underscores; no hyphens).
3. Inspect the wrapped inner error (%w) for the exact SQL error and fix accordingly.
4. If the data dir is corrupt and unrecoverable, archive it and re-initialize / re-pull from remote.

Example fix

// before (.beads/metadata.json)
{ "dolt_database": "my-issues-db" } // hyphens rejected / problematic

// after
{ "dolt_database": "my_issues_db" }

var dbCfg struct{ DoltDatabase string `json:"dolt_database"` }
json.Unmarshal(meta, &dbCfg)
valid := regexp.MustCompile(`^[A-Za-z0-9_]+$`)
if dbCfg.DoltDatabase != "" && !valid.MatchString(dbCfg.DoltDatabase) {
    return fmt.Errorf("dolt_database %q invalid; use underscores, not hyphens", dbCfg.DoltDatabase)
}

if err := store.Init(ctx); err != nil {
    if strings.Contains(err.Error(), "creating database") {
        // run 'bd doctor', inspect inner SQL error
        return fmt.Errorf("db creation failed: %w", err)
    }
    return err
}

When it happens

Trigger: newStore -> initSchema where s.database != "" and the CREATE DATABASE statement fails: (1) context cancelled mid-execution; (2) pinned connection broken (engine crash); (3) an object name conflict the engine rejects (reserved-name edge case passing the regex); (4) storage layer failure writing new database metadata.

Common situations: Configured dolt_database in .beads/metadata.json refers to a database the engine cannot create due to prior partial/corrupt initialization; transient engine failure; long-running init with expired context.

Related errors

• ensure global db: failed to create %s: %w
• embeddeddolt: switching to database: %w
• checking issue count: %w
• importing config %q: %w
• setting issue_prefix: %w

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