{"record":{"id":"8a139e6dc624353d","repo":"influxdata/influxdb","slug":"unexpected-error-while-migrating-v2-catalog-wraps-apply","errorCode":null,"errorMessage":"Unexpected error while migrating v2 catalog (wraps apply_records failure)","messagePattern":"Unexpected error while migrating v2 catalog \\(wraps apply_records failure\\)","errorType":"error_code","errorClass":"MigrationError","httpStatus":null,"severity":"critical","filePath":"influxdb3_catalog/src/catalog/migrations/v3.rs","lineNumber":115,"sourceCode":"    }\n\n    let v2_catalog = ser::v2::load_catalog(Arc::clone(&prefix), &v2_store)\n        .await?\n        .expect(\"v2 catalog should exist since checkpoint was found\");\n\n    let catalog_uuid = v2_catalog.catalog_uuid;\n    let catalog_sequence = v2_catalog.sequence_number();\n    let v2_snapshot = v2_catalog.snapshot();\n    let batch = synthesize_records(&v2_snapshot);\n\n    let mut v3_inner = V3InnerCatalog::new(Arc::clone(&prefix), catalog_uuid);\n    apply_records(\n        batch.as_slice(),\n        &mut v3_inner,\n        catalog_sequence,\n        RestorePreload::empty(),\n    )\n    .map_err(|e| MigrationError::Unexpected(anyhow::anyhow!(e)))?;\n    let v3_snapshot_bytes = v3_inner.create_snapshot();\n\n    if !v2_catalog.has_upgraded {\n        let next_sequence = catalog_sequence.next();\n        if let PersistCatalogResult::AlreadyExists =\n            v2_store.persist_upgrade_log(next_sequence).await?\n        {\n            return Err(MigrationError::UpgradeLogAlreadyExists);\n        }\n    } else {\n        info!(\"skipping write of UpgradedLog, as it is already present\");\n    }\n\n    info!(\"writing the v3 catalog snapshot\");\n    match v3_store.initialize_snapshot(v3_snapshot_bytes).await? {\n        MaybePutCatalogFile::Success(_) | MaybePutCatalogFile::AlreadyExists => {\n            Ok(MigrationResult::Migrated)\n        }","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/influxdata/influxdb/blob/06200ef96ba82c5f6727e5038a83af8e722c6875/influxdb3_catalog/src/catalog/migrations/v3.rs#L97-L133","documentation":"`MigrationError::Unexpected` wrapping a failure of `apply_records` during the v2->v3 catalog migration. `apply_records` replays synthesized v2 snapshot records into the fresh v3 catalog; any error there (malformed record, constraint violation, internal bug) is wrapped as an unexpected/non-categorized migration error via anyhow.","triggerScenarios":"Calling `check_and_migrate_v2_to_v3` when replaying v2 snapshot records into the v3 in-memory catalog fails — e.g. a v2 snapshot containing records the v3 `apply_records` parser rejects, duplicate ids, or out-of-order sequences.","commonSituations":"Migrating catalogs written by older v2 builds whose snapshots are not fully compatible with the current migration code; hand-edited or partially restored catalog objects; a bug in `synthesize_records`/`apply_records` surfaced by unusual v2 content.","solutions":["Read the wrapped `anyhow` cause in the error chain to identify which record type failed to apply.","Validate/repair the v2 snapshot data (dump it via `synthesize_records` paths or restore from a known-good backup).","Upgrade to the latest influxdb3 release — migration record-compat fixes are common.","If the v2 store is disposable, clear it (or the checkpoint) so the migration short-circuits with NothingToMigrate."],"exampleFix":"// before\napply_records(...).map_err(|e| MigrationError::Unexpected(anyhow::anyhow!(e)))?;\n// after (diagnose first)\nmatch apply_records(...) {\n    Ok(()) => {},\n    Err(e) => { log::error!(\"apply_records failed: {e:#?}\"); return Err(MigrationError::Unexpected(anyhow::anyhow!(e))); }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match check_and_migrate_v2_to_v3(prefix, store).await {\n    Ok(MigrationResult::Migrated) => info!(\"migrated\"),\n    Err(e) => {\n        // inspect the wrapped anyhow chain to find the failing record\n        error!(\"migration failed: {e:#}\");\n        return Err(e);\n    }\n}","preventionTips":["Keep client/server/catalog versions aligned before migrating.","Back up the v2 store before migration so you can retry from a clean state.","Test migration on a copy of production catalog data first.","Read the full error chain (anyhow `{e:#}`) to identify the exact failing record type."],"tags":["influxdb3","catalog-migration","migration","rust"],"backgroundTag":"database-write-failed","analyzedSha":"06200ef96ba82c5f6727e5038a83af8e722c6875","analyzedAt":"2026-09-19T12:55:30.003Z","contentChangedAt":"2026-09-19T12:55:30.003Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}