juanfont/headscale · critical

database type not supported

Error message

database type not supported

What it means

Internal sentinel in hscontrol/db/db.go returned by the database open path (db.go:1153-1157) when cfg.Type is neither 'sqlite' nor 'postgres'. The error is wrapped as "database of type %s is not supported", naming the offending value. Only those two GORM drivers are compiled in.

Source

Thrown at hscontrol/db/db.go:36

	"github.com/juanfont/headscale/hscontrol/policy"
	"github.com/juanfont/headscale/hscontrol/types"
	"github.com/juanfont/headscale/hscontrol/util"
	"github.com/rs/zerolog/log"
	"github.com/tailscale/squibble"
	"gorm.io/driver/postgres"
	"gorm.io/gorm"
	"gorm.io/gorm/logger"
	"gorm.io/gorm/schema"
)

//go:embed schema.sql
var dbSchema string

func init() {
	schema.RegisterSerializer("text", TextSerialiser{})
}

var errDatabaseNotSupported = errors.New("database type not supported")

var errForeignKeyConstraintsViolated = errors.New("foreign key constraints violated")

const (
	maxIdleConns   = 100
	maxOpenConns   = 100
	contextTimeout = 10 * time.Second
)

type HSDatabase struct {
	DB  *gorm.DB
	cfg *types.Config
}

// NewHeadscaleDatabase creates a new database connection and runs migrations.
// It accepts the full configuration to allow migrations access to policy settings.
//
//nolint:gocyclo // complex database initialization with many migrations

View on GitHub (pinned to 565fd254d0)

Solutions

1. Set database.type to exactly sqlite or postgres
2. If you typed 'postgresql' or 'sqlite3', correct it to 'postgres' / 'sqlite'
3. Check HEADSCALE_DB_TYPE env overrides in your systemd unit or container

Example fix

# before
database:
  type: mysql

# after
database:
  type: postgres

import "slices"

func validDBType(t string) bool {
    return slices.Contains([]string{types.DatabaseSqlite, types.DatabasePostgres}, t)
}

hsdb, err := db.NewHeadscaleDatabase(cfg, dbFn)
if err != nil {
    if errors.Is(err, errDatabaseNotSupported) {
        // operator-facing: name the exact value
        return fmt.Errorf("unsupported database.type %q (use sqlite or postgres)", cfg.Type)
    }
    return err
}

When it happens

Trigger: Setting database.type in config.yaml (or the HEADSCALE_DB_TYPE env var) to anything other than sqlite/postgres — e.g. 'mysql', 'mariadb', 'sqlite3', or a value with stray whitespace/capitalization like 'SQLite'.

Common situations: Migrating from another tool and assuming MySQL is supported; typo or trailing spaces in the type field; env var override HEADSCALE_DB_TYPE=postgresql (wrong value).

Related errors

• STUN address not set
• initial DERPMap is empty, Headscale requires at least one en
• path cannot be empty
• unsupported policy mode
• foreign key constraints violated

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/e36e35c0920b9fe6. Report an issue: GitHub.