gastownhall/beads · error

invalid database name %q: %v

Error message

invalid database name %q: %v

What it means

Wraps dolt.ValidateDatabaseName's error when the --database flag value is not a valid Dolt database name. Validation runs early in init, before any side effects, and the %v carries the specific rule the name violated.

Source

Thrown at cmd/bd/init.go:560

			return fmt.Errorf("unknown backend %q: the supported backend is \"dolt\" (default)", backendFlag)
		}
		// A registered extension backend passes IsSupportedBackend so its
		// existing workspaces can be opened, but init provisions Dolt only and
		// would otherwise create the workspace and persist backend: dolt. Reject
		// it here rather than silently creating the wrong workspace; downstream
		// registrants supply their own workspace-creation path.
		if backends.Registered(backendFlag) {
			return fmt.Errorf("backend %q cannot be created by bd init; it can only open an existing workspace (bd init provisions \"dolt\", the default)", backendFlag)
		}
		for _, legacyFlag := range removedBackendInitFlags {
			if cmd.Flags().Changed(legacyFlag.name) {
				return fmt.Errorf("--%s belonged to %s: %s; use --backend=dolt (the default)", legacyFlag.name, legacyFlag.origin, legacyFlag.rationale)
			}
		}
		// Validate --database format early, before any side effects.
		if database != "" {
			if err := dolt.ValidateDatabaseName(database); err != nil {
				return fmt.Errorf("invalid database name %q: %v", database, err)
			}
		}

		// Resolve non-interactive mode: flag > env var > terminal detection.
		// This must be computed before any interactive prompts.
		nonInteractive := isNonInteractiveInit(nonInteractiveFlag)

		// Validate --role flag value
		if roleFlag != "" {
			switch roleFlag {
			case "maintainer", "contributor":
				// valid
			default:
				return fmt.Errorf("invalid --role %q: must be \"maintainer\" or \"contributor\"", roleFlag)
			}
		}

		// Fail-fast: contributor/team wizards require interaction

View on GitHub (pinned to 71377f2769)

Solutions

  1. Use only letters, digits, and underscores; start with a letter or underscore
  2. Convert hyphens to underscores: my-project → my_project
  3. Check the wrapped %v message for the exact violated rule
  4. Drop --database and let init choose the default database name

Example fix

// before
bd init --database=my-project
// after
bd init --database=my_project
Defensive patterns

Strategy: validation

Validate before calling

var dbRE = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
if database != "" && !dbRE.MatchString(database) {
    return fmt.Errorf("database name %q invalid; use letters, digits, underscores", database)
}

Try / catch

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

Prevention

When it happens

Trigger: `bd init --database=<name>` where name fails dolt.ValidateDatabaseName (e.g. contains hyphens, spaces, special chars, starts with a digit, or is empty-string-adjacent malformed).

Common situations: Using hyphenated project names ('my-project') as database names, spaces or slashes from paths, names copied from directory names with invalid characters.

Related errors

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