{"record":{"id":"e36e35c0920b9fe6","repo":"juanfont/headscale","slug":"database-type-not-supported","errorCode":null,"errorMessage":"database type not supported","messagePattern":"database type not supported","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"hscontrol/db/db.go","lineNumber":36,"sourceCode":"\t\"github.com/juanfont/headscale/hscontrol/policy\"\n\t\"github.com/juanfont/headscale/hscontrol/types\"\n\t\"github.com/juanfont/headscale/hscontrol/util\"\n\t\"github.com/rs/zerolog/log\"\n\t\"github.com/tailscale/squibble\"\n\t\"gorm.io/driver/postgres\"\n\t\"gorm.io/gorm\"\n\t\"gorm.io/gorm/logger\"\n\t\"gorm.io/gorm/schema\"\n)\n\n//go:embed schema.sql\nvar dbSchema string\n\nfunc init() {\n\tschema.RegisterSerializer(\"text\", TextSerialiser{})\n}\n\nvar errDatabaseNotSupported = errors.New(\"database type not supported\")\n\nvar errForeignKeyConstraintsViolated = errors.New(\"foreign key constraints violated\")\n\nconst (\n\tmaxIdleConns   = 100\n\tmaxOpenConns   = 100\n\tcontextTimeout = 10 * time.Second\n)\n\ntype HSDatabase struct {\n\tDB  *gorm.DB\n\tcfg *types.Config\n}\n\n// NewHeadscaleDatabase creates a new database connection and runs migrations.\n// It accepts the full configuration to allow migrations access to policy settings.\n//\n//nolint:gocyclo // complex database initialization with many migrations","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/db/db.go#L18-L54","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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).","solutions":["Set database.type to exactly sqlite or postgres","If you typed 'postgresql' or 'sqlite3', correct it to 'postgres' / 'sqlite'","Check HEADSCALE_DB_TYPE env overrides in your systemd unit or container"],"exampleFix":"# before\ndatabase:\n  type: mysql\n\n# after\ndatabase:\n  type: postgres","handlingStrategy":"validation","validationCode":"import \"slices\"\n\nfunc validDBType(t string) bool {\n    return slices.Contains([]string{types.DatabaseSqlite, types.DatabasePostgres}, t)\n}","typeGuard":null,"tryCatchPattern":"hsdb, err := db.NewHeadscaleDatabase(cfg, dbFn)\nif err != nil {\n    if errors.Is(err, errDatabaseNotSupported) {\n        // operator-facing: name the exact value\n        return fmt.Errorf(\"unsupported database.type %q (use sqlite or postgres)\", cfg.Type)\n    }\n    return err\n}","preventionTips":["Validate database.type at config-load time against {sqlite, postgres}","Pin config values in CI config checks before deploy","Watch for env-var overrides (HEADSCALE_DB_TYPE) shadowing the YAML"],"tags":["config","database","startup","headscale"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}