{"record":{"id":"a9e88fe10ed18e32","repo":"juanfont/headscale","slug":"loading-users-for-requesttags-migration-w","errorCode":null,"errorMessage":"loading users for RequestTags migration: %w","messagePattern":"loading users for RequestTags migration: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"hscontrol/db/db.go","lineNumber":622,"sourceCode":"\t\t\t\t// Fixes: https://github.com/juanfont/headscale/issues/3006\n\t\t\t\tID: \"202601121700-migrate-hostinfo-request-tags\",\n\t\t\t\tMigrate: func(tx *gorm.DB) error {\n\t\t\t\t\t// 1. Load policy from file or database based on configuration\n\t\t\t\t\tpolicyData, err := PolicyBytes(tx, cfg)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\tlog.Warn().Err(err).Msg(\"failed to load policy, skipping RequestTags migration (tags will be validated on node reconnect)\")\n\t\t\t\t\t\treturn nil\n\t\t\t\t\t}\n\n\t\t\t\t\tif len(policyData) == 0 {\n\t\t\t\t\t\tlog.Info().Msg(\"no policy found, skipping RequestTags migration (tags will be validated on node reconnect)\")\n\t\t\t\t\t\treturn nil\n\t\t\t\t\t}\n\n\t\t\t\t\t// 2. Load users and nodes to create PolicyManager\n\t\t\t\t\tusers, err := ListUsers(tx, nil)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn fmt.Errorf(\"loading users for RequestTags migration: %w\", err)\n\t\t\t\t\t}\n\n\t\t\t\t\tnodes, err := ListNodes(tx)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn fmt.Errorf(\"loading nodes for RequestTags migration: %w\", err)\n\t\t\t\t\t}\n\n\t\t\t\t\t// 3. Create PolicyManager (handles HuJSON parsing, groups, nested tags, etc.)\n\t\t\t\t\tpolMan, err := policy.NewPolicyManager(policyData, users, nodes.ViewSlice())\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\tlog.Warn().Err(err).Msg(\"failed to parse policy, skipping RequestTags migration (tags will be validated on node reconnect)\")\n\t\t\t\t\t\treturn nil\n\t\t\t\t\t}\n\n\t\t\t\t\t// 4. Process each node\n\t\t\t\t\tfor _, node := range nodes {\n\t\t\t\t\t\tif node.Hostinfo == nil {\n\t\t\t\t\t\t\tcontinue","sourceCodeStart":604,"sourceCodeEnd":640,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/db/db.go#L604-L640","documentation":"Migration '202511131445' (RequestTags migration, following the forced_tags rename) fails calling ListUsers(tx, nil) while loading all users to construct a PolicyManager that validates historical --advertise-tags values. The wrapped error is a database query failure: schema/type mismatch on the users table, permission problem, or connection loss mid-migration.","triggerScenarios":"The users table schema does not match what ListUsers expects (schema drift from out-of-order upgrades), the migration runs on a Postgres connection that drops, or the SELECT hits a lock timeout while another transaction holds users.","commonSituations":"Upgrading a database that previously ran mixed headscale versions; long-running admin transactions blocking the migration read; Postgres restart or failover during startup.","solutions":["Check the wrapped error - a SQL 'column does not exist' means schema drift: verify migrations table ordering and reconcile (see the forced_tags rename guidance)","Ensure the migration runs with the database idle (stop other headscale/admin clients during upgrade)","For flaky Postgres connectivity, fix the network/pool settings (conn max lifetime) and restart headscale so the migration transaction retries from the top","Restore from backup if the schema/history mismatch cannot be reconciled"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Pre-flight: schema and connectivity are sane before upgrade\nif err := db.Ping(); err != nil { log.Fatalf(\"db unreachable: %v\", err) }\nif _, err := db.Exec(\"SELECT 1 FROM users LIMIT 1\"); err != nil {\n\tlog.Fatalf(\"users unreadable, migration will fail: %v\", err)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the schema and the migrations bookkeeping table backed up together (pg_dump includes both)","Avoid schema drift: only headscale itself should issue DDL against its database","Monitor DB connection stability before scheduling an upgrade"],"tags":["database","migration","users","policy","schema-drift"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}