{"record":{"id":"62912208662a1b1e","repo":"hashicorp/nomad","slug":"wal-directory-already-exists-at-s-remove-it-befo","errorCode":null,"errorMessage":"WAL directory already exists at %s; remove it before retrying migration","messagePattern":"WAL directory already exists at (.+?); remove it before retrying migration","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/raftutil/migrate.go","lineNumber":191,"sourceCode":"\tfor msg := range sub {\n\t\tselect {\n\t\tcase parent <- msg:\n\t\tdefault:\n\t\t\t// Drop message if consumer is slow to avoid blocking migration.\n\t\t}\n\t}\n}\n\nfunc preflightChecks(boltPath, walDir, raftDir string) error {\n\t// Verify the BoltDB file exists.\n\tboltInfo, err := os.Stat(boltPath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"BoltDB store not found at %s: %w\", boltPath, err)\n\t}\n\n\t// Verify the WAL directory does not already exist.\n\tif _, err := os.Stat(walDir); err == nil {\n\t\treturn fmt.Errorf(\n\t\t\t\"WAL directory already exists at %s; remove it before retrying migration\",\n\t\t\twalDir)\n\t}\n\n\t// Check write permissions on raft directory.\n\ttestFile := filepath.Join(raftDir, \".permission-test\")\n\tif err := os.WriteFile(testFile, []byte(\"test\"), 0o600); err != nil {\n\t\treturn fmt.Errorf(\"insufficient write permissions in %s: %w\", raftDir, err)\n\t}\n\tos.Remove(testFile)\n\n\t// Check available disk space.\n\tusage, err := disk.Usage(raftDir)\n\tif err != nil {\n\t\t// Log warning but don't fail migration - disk space check is advisory.\n\t\treturn fmt.Errorf(\"unable to check available disk space: %w\", err)\n\t}\n\tavailableSpace := usage.Free","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/raftutil/migrate.go#L173-L209","documentation":"preflightChecks refuses to run if <raftDir>/wal already exists, because a pre-existing WAL directory could contain partial data from an earlier run and MigrateToWAL does not merge into an existing store. This is a deliberate safety guard: migration only proceeds into a fresh wal directory. No state is modified.","triggerScenarios":"os.Stat(walDir) succeeds, meaning <raftDir>/wal exists: leftover from a previous cleanup failure (notably Windows handle-release delays), a previous successful migration (wal present but raft.db also present after a failed rename), or manually created directory.","commonSituations":"Retrying migration after a previous attempt whose cleanupWAL could not remove the directory; re-running migration after an error 1887 (rename failure) left both wal and raft.db in place; operator created the directory by hand or restored a backup into it.","solutions":["Confirm the previous migration did not complete (no raft.db.migrated.<timestamp> backup); if it did, do not re-migrate — just start the server.","If migration never completed, stop the server and remove the stale directory: rm -rf <raftDir>/wal, then re-run.","On Windows, close processes holding files in wal/ open before removing it.","Inspect wal/ contents before deleting to ensure it contains no live server data (server must be stopped)."],"exampleFix":"// before\nMigrateToWAL(ctx, raftDir, progress) // fails: wal/ already exists\n// after (server stopped, migration not previously completed)\n// rm -rf <raftDir>/wal\nMigrateToWAL(ctx, raftDir, progress)","handlingStrategy":"validation","validationCode":"walDir := filepath.Join(raftDir, \"wal\")\nif _, err := os.Stat(walDir); err == nil {\n    if _, err := os.Stat(filepath.Join(raftDir, \"raft.db\")); err != nil {\n        return fmt.Errorf(\"wal exists but raft.db is gone: migration already completed; do not re-run\")\n    }\n    return fmt.Errorf(\"stale %s present; server stopped? remove it before retrying\", walDir)\n}","typeGuard":null,"tryCatchPattern":"err := raftutil.MigrateToWAL(ctx, raftDir, progress)\nif err != nil && strings.Contains(err.Error(), \"WAL directory already exists\") {\n    // inspect: if raft.db.migrated.* exists, migration done — start server.\n    // else, remove the stale wal/ (server stopped) and retry once.\n}","preventionTips":["Only re-run migration after confirming the previous attempt failed (no raft.db.migrated.* backup).","Stop the server and delete leftover wal/ directories before retrying, especially on Windows.","Never create or restore data into <raftDir>/wal manually.","Check error 1887 (rename failure) history — it leaves both wal/ and raft.db in place."],"tags":["filesystem","preflight","migration","idempotency"],"backgroundTag":"wal-directory-already-exists","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}