semaphoreui/semaphore · error

BoltDB not supported

Error message

BoltDB not supported

What it means

Semaphore no longer supports BoltDB as a database backend. When the resolved database dialect is 'bolt', GetDBConfig (connection string construction) returns the error 'BoltDB not supported' instead of a connection string, and callers abort (e.g. HTTP handlers respond 400).

Solutions

1. Migrate data off BoltDB (export via the old version, e.g. `semaphore export` / project JSON export)
2. Change config to a supported dialect: mysql, postgres (or sqlite), with the corresponding connection section
3. Remove the `bolt` section / set `dialect` explicitly to the new backend
4. Restore an exported dataset into MySQL/Postgres before starting the new version

Example fix

// before (config.json)
{"dialect": "bolt", "bolt": {"host": "db.bolt"}}
// after
{"dialect": "mysql", "mysql": {"host": "db:3306", "user": "semaphore", "pass": "...", "name": "semaphore"}}

// reject bolt before calling into semaphore DB config
if strings.EqualFold(cfg.Dialect, "bolt") {
    return errors.New("BoltDB is unsupported; migrate to mysql/postgres/sqlite first")
}

// handlers should translate the returned error instead of crashing
if err := dbSetup(cfg); err != nil {
    helpers.WriteErrorStatus(w, err.Error(), http.StatusBadRequest)
    return
}

When it happens

Trigger: config has `dialect: bolt` (or only a bolt section), and code that builds a DB connection string (GetDBConfig / buildConnectionString) hits `case DbDriverBolt: err = errors.New("BoltDB not supported")`.

Common situations: Upgrading an old Semaphore installation that used BoltDB to a current version; copying legacy config.json with dialect 'bolt' into a new deployment.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• unsupported database driver
• database configuration not found
• BoltDB is not supported starting from version 2.19
• migration version is empty
• invalid migration version format

AI-assisted analysis of semaphoreui/semaphore@1774ccb71a (2026-09-07). Data as JSON: /api/errors/55e5ab5b5e418ba2. Report an issue: GitHub.

Appendix: source

Thrown at util/config.go:2029

// GetConnectionString constructs the database connection string based on the current configuration.
// It supports MySQL, BoltDB, and PostgreSQL dialects.
// If the dialect is unsupported, it returns an error.
//
// Parameters:
// - includeDbName: a boolean indicating whether to include the database name in the connection string.
//
// Returns:
// - connectionString: the constructed database connection string.
// - err: an error if the dialect is unsupported.
func (d *DbConfig) GetConnectionString(includeDbName bool) (connectionString string, err error) {
	dbName := d.GetDbName()
	dbUser := d.GetUsername()
	dbPass := d.GetPassword()
	dbHost := d.GetHostname()

	switch d.Dialect {
	case DbDriverBolt:
		err = errors.New("BoltDB not supported")
		return
	case DbDriverMySQL:
		if includeDbName {
			connectionString = fmt.Sprintf(
				"%s:%s@tcp(%s)/%s",
				dbUser,
				dbPass,
				dbHost,
				dbName)
		} else {
			connectionString = fmt.Sprintf(
				"%s:%s@tcp(%s)/",
				dbUser,
				dbPass,
				dbHost)
		}
		options := map[string]string{
			"parseTime":         "true",

View on GitHub (pinned to 1774ccb71a)