{"record":{"id":"eaa55b9130576f5f","repo":"AdguardTeam/AdGuardHome","slug":"unknown-target-schema-version-d","errorCode":null,"errorMessage":"unknown target schema version %d","messagePattern":"unknown target schema version (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/configmigrate/migrator.go","lineNumber":94,"sourceCode":"\n\tbuf := bytes.NewBuffer(newBody)\n\tenc := yaml.NewEncoder(buf)\n\tenc.SetIndent(2)\n\n\tif err = enc.Encode(diskConf); err != nil {\n\t\treturn body, false, fmt.Errorf(\"generating new config: %w\", err)\n\t}\n\n\treturn buf.Bytes(), true, nil\n}\n\n// validateVersion validates the current and desired schema versions.\nfunc validateVersion(current, target uint) (err error) {\n\tswitch {\n\tcase current > target:\n\t\treturn fmt.Errorf(\"unknown current schema version %d\", current)\n\tcase target > LastSchemaVersion:\n\t\treturn fmt.Errorf(\"unknown target schema version %d\", target)\n\tcase target < current:\n\t\treturn fmt.Errorf(\"target schema version %d lower than current %d\", target, current)\n\tdefault:\n\t\treturn nil\n\t}\n}\n\n// migrateFunc is a function that upgrades a config and returns an error.\ntype migrateFunc = func(ctx context.Context, diskConf yobj) (err error)\n\n// upgradeConfigSchema upgrades the configuration schema in diskConf from\n// current to target version.  current must be less than target, and both must\n// be non-negative and less or equal to [LastSchemaVersion].\nfunc (m *Migrator) upgradeConfigSchema(\n\tctx context.Context,\n\tcurrent, target uint,\n\tdiskConf yobj,\n) (err error) {","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/configmigrate/migrator.go#L76-L112","documentation":"validateVersion rejects the requested target schema version because it is higher than LastSchemaVersion known to this build. The library refuses to write a schema version it has no migrations for.","triggerScenarios":"Calling Migrate with a target greater than LastSchemaVersion, e.g. hardcoding a future version number or mixing builds with different configmigrate packages.","commonSituations":"Hardcoded target versions in deployment scripts that outlive a binary upgrade; using constants from a newer module version than the compiled binary.","solutions":["Use configmigrate.LastSchemaVersion as the target instead of a literal number","Upgrade the module/binary to a version whose LastSchemaVersion covers the desired target"],"exampleFix":"// before\n_, _, err := configmigrate.Migrate(ctx, body, 99)\n\n// after\n_, _, err := configmigrate.Migrate(ctx, body, configmigrate.LastSchemaVersion)","handlingStrategy":"validation","validationCode":"if target > configmigrate.LastSchemaVersion { target = configmigrate.LastSchemaVersion }","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"unknown target schema version\") { /* retry with LastSchemaVersion */ }","preventionTips":["Never hardcode literal schema versions; use the package constant","Regenerate constants after upgrading the module"],"tags":["config","migration","version","schema"],"backgroundTag":"schema-version-mismatch","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}