{"record":{"id":"7b91cacbceebe2e3","repo":"AdguardTeam/AdGuardHome","slug":"migrating-schema-d-to-d-w","errorCode":null,"errorMessage":"migrating schema %d to %d: %w","messagePattern":"migrating schema (.+?) to (.+?): %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/configmigrate/migrator.go","lineNumber":157,"sourceCode":"\t\t25: m.migrateTo26,\n\t\t26: m.migrateTo27,\n\t\t27: m.migrateTo28,\n\t\t28: m.migrateTo29,\n\t\t29: m.migrateTo30,\n\t\t30: m.migrateTo31,\n\t\t31: m.migrateTo32,\n\t\t32: m.migrateTo33,\n\t\t33: m.migrateTo34,\n\t}\n\n\tfor i, migrate := range upgrades[current:target] {\n\t\tcur := current + uint(i)\n\t\tnext := current + uint(i) + 1\n\n\t\tm.logger.InfoContext(ctx, \"upgrade yaml\", \"from\", cur, \"to\", next)\n\n\t\tif err = migrate(ctx, diskConf); err != nil {\n\t\t\treturn fmt.Errorf(\"migrating schema %d to %d: %w\", cur, next, err)\n\t\t}\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":139,"sourceCodeEnd":163,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/configmigrate/migrator.go#L139-L163","documentation":"upgradeConfigSchema reports that an individual step migration (from schema cur to cur+1) failed, wrapping the step's error. The chain identifies exactly which schema transition broke and why.","triggerScenarios":"Calling Migrate where one of the per-version migration functions fails, e.g. addQUICPorts hitting a non-string upstream field (v10), an invalid bind_host (v23), or a malformed filters entry (v29).","commonSituations":"Configs hand-edited so a field has an unexpected type (a list where a string was expected), or partially corrupted files that still parse as YAML but have the wrong shape for a specific migration step.","solutions":["Read the wrapped cause; the \"from\"/\"to\" versions in the message tell you which migration step to inspect","Check the field mentioned by the inner error and correct its type/value in the config","Look at internal/configmigrate/v<from+1>.go to see exactly what shape that step expects"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"null // validate config shape per-step is impractical generically; pre-validate the specific field types your config uses (upstreams as strings, clients as objects, bind_host as IP)","typeGuard":null,"tryCatchPattern":"if _, _, err := configmigrate.Migrate(ctx, body, target); err != nil && strings.Contains(err.Error(), \"migrating schema\") { /* parse cur/next from message, inspect configmigrate/v<next>.go, fix field, retry */ }","preventionTips":["Back up the YAML before every migration","Avoid hand-editing typed fields; let AdGuard Home write its own config"],"tags":["config","migration","schema","step-failed"],"backgroundTag":"schema-migration-step-failed","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}