{"record":{"id":"d715de50ad355740","repo":"apache/answer","slug":"sync-version-failed-v","errorCode":null,"errorMessage":"sync version failed: %v","messagePattern":"sync version failed: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/migrations/migrations.go","lineNumber":122,"sourceCode":"\tNewMigration(\"v1.5.1\", \"add plugin kv storage\", addPluginKVStorage, true),\n\tNewMigration(\"v1.6.0\", \"move user config to interface\", moveUserConfigToInterface, true),\n\tNewMigration(\"v1.7.0\", \"add optional tags\", addOptionalTags, true),\n\tNewMigration(\"v1.7.2\", \"expand avatar column length\", expandAvatarColumnLength, false),\n\tNewMigration(\"v1.8.0\", \"change admin menu\", updateAdminMenuSettings, true),\n\tNewMigration(\"v1.8.1\", \"ai feat\", aiFeat, true),\n\tNewMigration(\"v2.0.1\", \"change avatar type to text\", updateAvatarType, false),\n\tNewMigration(\"v2.0.2\", \"add reasoning content to ai conversation record\", addAIConversationReasoningContent, false),\n\tNewMigration(\"v2.0.3\", \"add require email verification login setting\", addRequireEmailVerification, true),\n}\n\nfunc GetMigrations() []Migration {\n\treturn migrations\n}\n\n// GetCurrentDBVersion returns the current db version\nfunc GetCurrentDBVersion(engine *xorm.Engine) (int64, error) {\n\tif err := engine.Sync(new(entity.Version)); err != nil {\n\t\treturn -1, fmt.Errorf(\"sync version failed: %v\", err)\n\t}\n\n\tcurrentVersion := &entity.Version{ID: 1}\n\thas, err := engine.Get(currentVersion)\n\tif err != nil {\n\t\treturn -1, fmt.Errorf(\"get first version failed: %v\", err)\n\t}\n\tif !has {\n\t\t_, err := engine.InsertOne(&entity.Version{ID: 1, VersionNumber: 0})\n\t\tif err != nil {\n\t\t\treturn -1, fmt.Errorf(\"insert first version failed: %v\", err)\n\t\t}\n\t\treturn 0, nil\n\t}\n\treturn currentVersion.VersionNumber, nil\n}\n\n// ExpectedVersion returns the expected db version","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/apache/answer/blob/3b9f1370612e690a0b7f230f05e688930db4c6d3/internal/migrations/migrations.go#L104-L140","documentation":"GetCurrentDBVersion syncs the entity.Version table with xorm before reading the schema version. If engine.Sync fails (it cannot create/alter the version table), the error is wrapped as 'sync version failed: %v' and Migrate aborts with -1.","triggerScenarios":"engine.Sync(new(entity.Version)) returns an error: DB unreachable, insufficient DDL privileges to create/alter table `version`, table schema conflicts xorm cannot reconcile, or context timeout.","commonSituations":"First bootstrap on a fresh database where DDL is denied; production DB with read-only migration user; xorm tag changes on entity.Version conflicting with existing table; transient connection drops.","solutions":["Check the underlying DB error after 'sync version failed:'","Run migrations with a user that has CREATE/ALTER privileges","Verify network connectivity to the database and that it accepts DDL","Manually inspect the `version` table for conflicts with entity.Version fields"],"exampleFix":"// before\nif err := engine.Sync(new(entity.Version)); err != nil {\n    return -1, fmt.Errorf(\"sync version failed: %v\", err)\n}\n// after\nif err := engine.Sync(new(entity.Version)); err != nil {\n    return -1, fmt.Errorf(\"sync version failed: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":"// pre-check DDL capability\nif _, err := engine.Exec(\"SELECT 1\"); err != nil {\n    return fmt.Errorf(\"db not ready: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"version, err := migrations.GetCurrentDBVersion(engine)\nif err != nil {\n    if strings.HasPrefix(err.Error(), \"sync version failed\") {\n        log.Errorf(\"cannot sync version table, check DDL privileges: %v\", err)\n    }\n    return err\n}","preventionTips":["Grant CREATE/ALTER privileges to the migration user","Run Migrate against the primary, not a replica","Keep entity.Version xorm tags stable across releases","Check DB connectivity before starting migrations"],"tags":["database","migration","xorm","schema-sync"],"backgroundTag":"schema-sync-failed","analyzedSha":"3b9f1370612e690a0b7f230f05e688930db4c6d3","analyzedAt":"2026-09-05T18:18:39.533Z","contentChangedAt":"2026-09-05T18:18:39.533Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}