{"record":{"id":"9261d3512a029cef","repo":"gofr-dev/gofr","slug":"failed-to-record-migration-w","errorCode":null,"errorMessage":"failed to record migration: %w","messagePattern":"failed to record migration: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/gofr/migration/elasticsearch.go","lineNumber":164,"sourceCode":"\treturn em.migrator.beginTransaction(c)\n}\n\n// commitMigration records the migration in the tracking index.\nfunc (em elasticsearchMigrator) commitMigration(c *container.Container, data transactionData) error {\n\tif data.UsedDatasources[dsElasticsearch] {\n\t\tmigrationDoc := map[string]any{\n\t\t\t\"version\":    data.MigrationNumber,\n\t\t\t\"method\":     \"UP\",\n\t\t\t\"start_time\": data.StartTime.Format(time.RFC3339),\n\t\t\t\"duration\":   time.Since(data.StartTime).Milliseconds(),\n\t\t}\n\n\t\t// Use the migration number as the document ID for idempotency\n\t\tdocID := fmt.Sprintf(\"%d\", data.MigrationNumber)\n\n\t\terr := c.Elasticsearch.IndexDocument(context.Background(), elasticsearchMigrationIndex, docID, migrationDoc)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to record migration: %w\", err)\n\t\t}\n\n\t\tc.Debugf(\"Inserted record for migration %v in Elasticsearch gofr_migrations index\", data.MigrationNumber)\n\t}\n\n\treturn em.migrator.commitMigration(c, data)\n}\n\n// rollback is a no-op for Elasticsearch migrations.\nfunc (em elasticsearchMigrator) rollback(c *container.Container, data transactionData) {\n\tem.migrator.rollback(c, data)\n\tc.Fatalf(\"Migration %v failed.\", data.MigrationNumber)\n}\n\nfunc (em elasticsearchMigrator) lock(ctx context.Context, cancel context.CancelFunc, c *container.Container, ownerID string) error {\n\treturn em.migrator.lock(ctx, cancel, c, ownerID)\n}\n","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/gofr-dev/gofr/blob/187eb24962502e91f1fee856230670958b66e89c/pkg/gofr/migration/elasticsearch.go#L146-L182","documentation":"Thrown when IndexDocument fails while persisting a migration record (document ID = migration number for idempotency) into the gofr_migrations index during commitMigration. The migration itself ran, but its record could not be written, so subsequent runs may re-execute it. The wrapped error holds the actual ES failure.","triggerScenarios":"c.Elasticsearch.IndexDocument() returns an error for the migration doc: ES down, mapping conflict on the index, document too large, write/403 permission, or version conflict on the same doc ID.","commonSituations":"Index created earlier with an incompatible mapping; read-only cluster due to disk watermark; network blip mid-migration; ES credentials lacking write access.","solutions":["Check the wrapped ES error for the specific cause (mapping/permissions/cluster state)","Ensure the gofr_migrations index allows writes and has a compatible mapping","Restore ES availability, then re-run the migration — doc ID idempotency makes it safe","Clear disk-watermark read-only blocks if the index is read-only"],"exampleFix":"// before\n// commit fails: failed to record migration: version_conflict_engine_exception\n// after\n// verify doc for this migration number isn't already applied, then retry commit\n_, err := c.Elasticsearch.GetDocument(ctx, \"gofr_migrations\", fmt.Sprintf(\"%d\", data.MigrationNumber))\nif err != nil { return em.commitMigration(c, data) } // idempotent retry","handlingStrategy":"retry","validationCode":"// pre-check write access\nif err := c.Elasticsearch.IndexDocument(ctx, \"gofr_migrations\", \"_healthcheck\", map[string]string{\"ping\":\"1\"}); err != nil {\n    return fmt.Errorf(\"gofr_migrations index not writable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"err := migrator.Run(c)\nif err != nil && strings.Contains(err.Error(), \"failed to record migration\") {\n    // document ID is idempotent: safe to retry with backoff\n    time.Sleep(2 * time.Second)\n    err = migrator.Run(c)\n}","preventionTips":["Validate index mapping compatibility before upgrading gofr versions","Monitor disk usage to avoid disk-watermark read-only blocks","Use credentials with write access to gofr_migrations","Rely on doc-ID idempotency to make retries safe"],"tags":["elasticsearch","migration","write-failure"],"backgroundTag":"elasticsearch-index-document-failed","analyzedSha":"187eb24962502e91f1fee856230670958b66e89c","analyzedAt":"2026-09-01T20:34:54.554Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}