invalid database name: %q; hyphens are not allowed in embedd

Error message

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'

What it means

OpenSQL() validates the database name against validIdentifier before switching to it; embedded Dolt cannot use hyphens in database names, so a name like 'my-db' fails to open. The error message explicitly points at .beads/metadata.json's dolt_database field and 'bd doctor' as the fix.

Source

Thrown at internal/storage/embeddeddolt/open.go:83

			dbErr = nil
		}
		if errors.Is(connErr, context.Canceled) {
			connErr = nil
		}
		return errors.Join(dbErr, connErr)
	}

	if err := db.PingContext(ctx); err != nil {
		return nil, nil, errors.Join(err, cleanup())
	}

	if strings.TrimSpace(database) != "" {
		if !validIdentifier.MatchString(database) {
			msg := fmt.Sprintf("invalid database name: %q", database)
			if strings.ContainsRune(database, '-') {
				msg += "; hyphens are not allowed in embedded mode — replace with underscores in .beads/metadata.json dolt_database field, or run 'bd doctor'"
			}
			return nil, nil, errors.Join(errors.New(msg), cleanup())
		}
		if _, err := db.ExecContext(ctx, "USE `"+database+"`"); err != nil {
			return nil, nil, errors.Join(err, cleanup())
		}
		if strings.TrimSpace(branch) != "" {
			if _, err := db.ExecContext(ctx, fmt.Sprintf("SET @@%s_head_ref = %s", database, sqlStringLiteral(branch))); err != nil {
				return nil, nil, errors.Join(err, cleanup())
			}
		}
	}

	return db, cleanup, nil
}

func buildDSN(dir, database string) string {
	v := url.Values{}
	v.Set(doltembed.CommitNameParam, commitName)
	v.Set(doltembed.CommitEmailParam, commitEmail)

View on GitHub (pinned to 71377f2769)

Solutions

Edit .beads/metadata.json and change dolt_database to use underscores (my-db → my_db)
Run `bd doctor` which offers to repair the database name automatically
If the DB was already created with the old name, export/re-import (bd export / bd import) into the underscore-named database

Example fix

// before (.beads/metadata.json)
{"dolt_database": "my-project-db"}
// after
{"dolt_database": "my_project_db"}

Defensive patterns

Strategy: validation

Validate before calling

var validIdentifier = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
if !validIdentifier.MatchString(cfg.DoltDatabase) {
    return fmt.Errorf("dolt_database %q invalid; replace hyphens with underscores", cfg.DoltDatabase)
}

Type guard

func isValidDBName(name string) bool {
    return strings.TrimSpace(name) != "" && !strings.ContainsRune(name, '-')
}

Try / catch

db, cleanup, err := embeddeddolt.OpenSQL(ctx, dir, dbName, branch)
if err != nil {
    if strings.Contains(err.Error(), "hyphens are not allowed") {
        return fmt.Errorf("fix .beads/metadata.json dolt_database (use underscores): %w", err)
    }
    return err
}

Prevention

Derive database names from directory names via a sanitizer that maps '-' to '_'
Validate metadata.json at startup with the identifier regex
Run `bd doctor` after cloning projects into hyphenated directories

When it happens

Trigger: Opening an embedded Dolt store whose dolt_database value in .beads/metadata.json contains hyphens (or otherwise fails the identifier regex), typically because the value was derived from a repo/directory name like 'my-project'.

Common situations: Cloning a project whose directory name contains hyphens; hand-editing metadata.json; older tooling that auto-derived the database name from a hyphenated folder name.

Related errors

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