{"record":{"id":"ec146d36353a833c","repo":"apache/seatunnel","slug":"agent-is-running-pid-file-paths-getpidfile","errorCode":null,"errorMessage":"Agent is running (pid file ${paths.getPidFile()}); stop the agent before write operations.","messagePattern":"Agent is running \\(pid file (.+?)\\); stop the agent before write operations\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/command/db/DbWriteGuard.java","lineNumber":29,"sourceCode":" * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\npackage org.apache.seatunnel.edge.agent.starter.command.db;\n\nimport org.apache.seatunnel.edge.agent.starter.command.EdgeAgentPaths;\n\nimport java.io.IOException;\n\npublic class DbWriteGuard {\n\n    public static void requireWriteAllowed(EdgeAgentPaths paths, DbCommandArgs cli)\n            throws IOException {\n        if (!cli.isDryRun() && paths.agentRunning()) {\n            throw new IllegalStateException(\n                    \"Agent is running (pid file \"\n                            + paths.getPidFile()\n                            + \"); stop the agent before write operations.\");\n        }\n        if (!cli.isDryRun() && !cli.isYes()) {\n            throw new IllegalArgumentException(\"Write operations require --yes (or use --dry-run)\");\n        }\n    }\n}\n","sourceCodeStart":11,"sourceCodeEnd":39,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/command/db/DbWriteGuard.java#L11-L39","documentation":"DbWriteGuard.requireWriteAllowed() blocks destructive db write operations while the agent is running, because the agent holds the store and concurrent writes would corrupt it. It throws IllegalStateException when the pid file indicates a live agent and the command is not a dry run.","triggerScenarios":"Running a db write subcommand (without --dry-run) while the pid file at paths.getPidFile() exists and paths.agentRunning() is true.","commonSituations":"Forgetting to stop the agent service before doing maintenance writes; a stale pid file left behind after an unclean shutdown making the guard think the agent is alive; running maintenance from a different shell while the agent runs as a daemon.","solutions":["Stop the agent first, then rerun the write command","Verify the pid file is stale: if the recorded pid is not a live agent process, remove the pid file","Use --dry-run to preview the write without the guard blocking","Add --yes after stopping the agent, since writes also require explicit confirmation"],"exampleFix":"// before\ndb wal-repair ...\n// after\nagent stop\ndb wal-repair ... --yes","handlingStrategy":"validation","validationCode":"if (paths.agentRunning() && !cli.isDryRun()) {\n    throw new IllegalStateException(\"Agent running; stop it before write ops\");\n}\nDbWriteGuard.requireWriteAllowed(paths, cli);","typeGuard":"boolean writeAllowed(EdgeAgentPaths paths, DbCommandArgs cli) {\n    return cli.isDryRun() || !paths.agentRunning();\n}","tryCatchPattern":"try {\n    DbWriteGuard.requireWriteAllowed(paths, cli);\n} catch (IllegalStateException e) {\n    LOG.error(\"{} — run `agent stop` first\", e.getMessage());\n}","preventionTips":["Stop the agent service before any db write operation","Clean up stale pid files after unclean shutdowns","Use --dry-run first, and --yes only when the agent is confirmed stopped"],"tags":["cli","concurrency","guard"],"backgroundTag":"conflicting-config-options","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}