{"record":{"id":"2d44dc768fcc9d8c","repo":"gastownhall/beads","slug":"embeddeddolt-creating-database-w","errorCode":null,"errorMessage":"embeddeddolt: creating database: %w","messagePattern":"embeddeddolt: creating database: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/embeddeddolt/store.go","lineNumber":331,"sourceCode":"\t}\n\tdefer func() { _ = cleanup() }()\n\n\tconn, err := db.Conn(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"embeddeddolt: pin connection: %w\", err)\n\t}\n\tdefer conn.Close()\n\n\tif s.database != \"\" {\n\t\tif !validIdentifier.MatchString(s.database) {\n\t\t\tmsg := fmt.Sprintf(\"embeddeddolt: invalid database name: %q\", s.database)\n\t\t\tif strings.ContainsRune(s.database, '-') {\n\t\t\t\tmsg += \"; hyphens are not allowed in embedded mode — replace with underscores in .beads/metadata.json dolt_database field, or run 'bd doctor'\"\n\t\t\t}\n\t\t\treturn errors.New(msg)\n\t\t}\n\t\tif _, err := conn.ExecContext(ctx, \"CREATE DATABASE IF NOT EXISTS `\"+s.database+\"`\"); err != nil {\n\t\t\treturn fmt.Errorf(\"embeddeddolt: creating database: %w\", err)\n\t\t}\n\t\tif _, err := conn.ExecContext(ctx, \"USE `\"+s.database+\"`\"); err != nil {\n\t\t\treturn fmt.Errorf(\"embeddeddolt: switching to database: %w\", err)\n\t\t}\n\t\tif s.branch != \"\" {\n\t\t\tif _, err := conn.ExecContext(ctx, fmt.Sprintf(\"SET @@%s_head_ref = %s\", s.database, sqlStringLiteral(s.branch))); err != nil {\n\t\t\t\treturn fmt.Errorf(\"embeddeddolt: setting branch: %w\", err)\n\t\t\t}\n\t\t}\n\t}\n\n\t// Forward-drift guard: if this database's schema is AHEAD of the binary,\n\t// fail fast with a clear \"upgrade bd\" message before MigrateUp no-ops and a\n\t// later query dies on a dropped/renamed column. Embedded mode is the mode\n\t// the stale-binary incident (#4135/#4137) was observed in. The read-only\n\t// embedded open (OpenReadOnly) already guards this; the writable open did\n\t// not. Runs after the USE switch so the version read resolves against the\n\t// target database.","sourceCodeStart":313,"sourceCodeEnd":349,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/embeddeddolt/store.go#L313-L349","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run the command — a partial previous init often left inconsistent state; 'bd doctor' can verify it.","Check the dolt_database value in .beads/metadata.json is a plain identifier (letters, digits, underscores; no hyphens).","Inspect the wrapped inner error (%w) for the exact SQL error and fix accordingly.","If the data dir is corrupt and unrecoverable, archive it and re-initialize / re-pull from remote."],"exampleFix":"// before (.beads/metadata.json)\n{ \"dolt_database\": \"my-issues-db\" } // hyphens rejected / problematic\n\n// after\n{ \"dolt_database\": \"my_issues_db\" }","handlingStrategy":"validation","validationCode":"var dbCfg struct{ DoltDatabase string `json:\"dolt_database\"` }\njson.Unmarshal(meta, &dbCfg)\nvalid := regexp.MustCompile(`^[A-Za-z0-9_]+$`)\nif dbCfg.DoltDatabase != \"\" && !valid.MatchString(dbCfg.DoltDatabase) {\n    return fmt.Errorf(\"dolt_database %q invalid; use underscores, not hyphens\", dbCfg.DoltDatabase)\n}","typeGuard":null,"tryCatchPattern":"if err := store.Init(ctx); err != nil {\n    if strings.Contains(err.Error(), \"creating database\") {\n        // run 'bd doctor', inspect inner SQL error\n        return fmt.Errorf(\"db creation failed: %w\", err)\n    }\n    return err\n}","preventionTips":["Use only [A-Za-z0-9_] identifiers for dolt_database in .beads/metadata.json","Run 'bd doctor' after interrupted initializations","Avoid killing bd during first-time database creation","Keep a backup/remote sync so a failed create can be recovered from"],"tags":["embedded-dolt","sql","create-database"],"backgroundTag":"sql-execution-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}