{"record":{"id":"3e64409986ce741e","repo":"gastownhall/beads","slug":"embeddeddolt-invalid-database-name-q-hyphens-a","errorCode":null,"errorMessage":"embeddeddolt: invalid database name: %q; hyphens are not allowed in embedded mode — replace with underscores in .beads/metadata.json dolt_database field, or run 'bd doctor'","messagePattern":"embeddeddolt: invalid database name: %q; hyphens are not allowed in embedded mode — replace with underscores in \\.beads/metadata\\.json dolt_database field, or run 'bd doctor'","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/embeddeddolt/store.go","lineNumber":328,"sourceCode":"\tdb, cleanup, err := OpenSQL(ctx, s.dataDir, \"\", \"\")\n\tif err != nil {\n\t\treturn fmt.Errorf(\"embeddeddolt: open db: %w\", err)\n\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","sourceCodeStart":310,"sourceCodeEnd":346,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/embeddeddolt/store.go#L310-L346","documentation":"initSchema (invoked from newStore) validates the configured database name before creating/using it. Embedded Dolt forbids hyphens in database identifiers, so a name like 'my-db' fails store construction with guidance to fix .beads/metadata.json or run 'bd doctor'.","triggerScenarios":"Constructing an EmbeddedDoltStore (via Open and friends) whose database field contains hyphens or otherwise fails validIdentifier — typically a dolt_database value derived from a hyphenated project directory name.","commonSituations":"Beads initialized inside a directory like 'my-app-web'; manual metadata.json edits; projects migrated from layouts that allowed hyphens.","solutions":["Change dolt_database in .beads/metadata.json to underscores (my-db → my_db)","Run `bd doctor` to auto-repair the database name","If data exists under the old name, migrate it (export/import) into the underscore-named database before deleting the old one"],"exampleFix":"// before (.beads/metadata.json)\n{\"dolt_database\": \"team-beads\"}\n// after\n{\"dolt_database\": \"team_beads\"}","handlingStrategy":"validation","validationCode":"var validIdentifier = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)\nif !validIdentifier.MatchString(dbName) {\n    return fmt.Errorf(\"fix dolt_database in .beads/metadata.json: %q\", dbName)\n}","typeGuard":"func safeDBName(name string) bool {\n    return strings.TrimSpace(name) != \"\" && !strings.ContainsRune(name, '-')\n}","tryCatchPattern":"store, err := embeddeddolt.Open(ctx, dir, db, branch)\nif err != nil {\n    if strings.Contains(err.Error(), \"hyphens are not allowed\") {\n        return fmt.Errorf(\"run 'bd doctor' or use underscores in dolt_database: %w\", err)\n    }\n    return err\n}","preventionTips":["Sanitize directory-derived names: replace '-' with '_' before storing dolt_database","Validate metadata.json contents on load with the identifier regex","Run `bd doctor` when setting up a workspace in a hyphenated directory"],"tags":["go","embedded-dolt","configuration","database-name"],"backgroundTag":"invalid-database-name","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}