{"record":{"id":"121dacd8755bf588","repo":"tikv/tikv","slug":"failed-to-open-raftdb-for-migration","errorCode":null,"errorMessage":"failed to open raftdb for migration","messagePattern":"failed to open raftdb for migration","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"components/server/src/common.rs","lineNumber":848,"sourceCode":"        );\n        let should_dump = raft_data_state_machine.before_open_target();\n\n        let raft_config = config.raft_engine.config();\n        let raft_engine =\n            RaftLogEngine::new(raft_config, key_manager.clone(), get_io_rate_limiter())\n                .expect(\"failed to open raft engine\");\n\n        if should_dump {\n            let config_raftdb = &config.raftdb;\n            let raft_db_opts = config_raftdb.build_opt(env.clone(), None);\n            let raft_cf_opts = config_raftdb.build_cf_opts(block_cache);\n            let raftdb = engine_rocks::util::new_engine_opt_with_snapshot_sequence_number_check(\n                &config.raft_store.raftdb_path,\n                raft_db_opts,\n                raft_cf_opts,\n                config_raftdb.enable_snapshot_sequence_number_check,\n            )\n            .expect(\"failed to open raftdb for migration\");\n            dump_raftdb_to_raft_engine(&raftdb, &raft_engine, 8 /* threads */);\n            raftdb.stop();\n            drop(raftdb);\n            raft_data_state_machine.after_dump_data();\n        }\n        (raft_engine, None)\n    }\n}\n\nconst DEFAULT_ENGINE_METRICS_RESET_INTERVAL: Duration = Duration::from_millis(60_000);\npub struct EngineMetricsManager<EK: KvEngine, ER: RaftEngine> {\n    tablet_registry: TabletRegistry<EK>,\n    kv_statistics: Option<Arc<RocksStatistics>>,\n    in_memory_engine_statistics: Option<Arc<InMemoryEngineStatistics>>,\n    kv_is_titan: bool,\n    raft_engine: ER,\n    raft_statistics: Option<Arc<RocksStatistics>>,\n    last_reset: Instant,","sourceCodeStart":830,"sourceCodeEnd":866,"githubUrl":"https://github.com/tikv/tikv/blob/78aedc1c81ef3f7d8bacc6e9d09f56460f134937/components/server/src/common.rs#L830-L866","documentation":"In the raftdb-to-raft-engine migration path, the server opens the existing raftdb (RocksDB) to dump its data into the raft engine, panicking if raftdb cannot be opened. The migration cannot proceed without reading the source data, so failure is fatal.","triggerScenarios":"ServerBuilder::build with raftdb as current storage and should_dump true, when new_engine_opt_with_snapshot_sequence_number_check fails on config.raft_store.raftdb_path — corrupt RocksDB data, stale LOCK, bad options, or decryption failures.","commonSituations":"Upgrading a cluster whose raftdb directory was damaged by an earlier crash; running migration while another process holds the data dir; switching from unencrypted to encrypted storage without proper key setup.","solutions":["Read the RocksDB error logged above the panic to identify lock vs corruption vs IO","Ensure the raftdb dir is not held by another process and permissions/disk are fine","Repair via tikv-ctl or restore from backup before retrying the migration"],"exampleFix":"// before (panic inside build)\n.expect(\"failed to open raftdb for migration\")\n// after (operator pre-check)\ntikv-ctl raft log --db /data/tikv/raft  # validate raftdb before restarting with raft-engine","handlingStrategy":"validation","validationCode":"// verify raftdb opens read-only before enabling raft-engine migration\nlet opts = ROpts::default(); // open with error_if_corrupt to validate\ntikv_ctl_check_raftdb(&config.raft_store.raftdb_path);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run tikv-ctl checks on raftdb before planning a migration","Ensure clean shutdowns (UPS) and regular backups","Resolve all LOCK holders before restart"],"tags":["raftdb","migration","startup","rocksdb"],"backgroundTag":"engine-open-failed","analyzedSha":"78aedc1c81ef3f7d8bacc6e9d09f56460f134937","analyzedAt":"2026-09-03T23:31:32.398Z","contentChangedAt":"2026-09-03T23:31:32.398Z","schemaVersion":2},"datasetVersion":"2026-09-11T07:07:21.782Z"}