apache/seatunnel · error · IllegalStateException

Agent is running (pid file ); stop the agent before write…

Error message

Agent is running (pid file ${paths.getPidFile()}); stop the agent before write operations.

What it means

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.

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

Example fix

// before
db wal-repair ...
// after
agent stop
db wal-repair ... --yes

Defensive patterns

Strategy: validation

Validate before calling

if (paths.agentRunning() && !cli.isDryRun()) {
    throw new IllegalStateException("Agent running; stop it before write ops");
}
DbWriteGuard.requireWriteAllowed(paths, cli);

Type guard

boolean writeAllowed(EdgeAgentPaths paths, DbCommandArgs cli) {
    return cli.isDryRun() || !paths.agentRunning();
}

Try / catch

try {
    DbWriteGuard.requireWriteAllowed(paths, cli);
} catch (IllegalStateException e) {
    LOG.error("{} — run `agent stop` first", e.getMessage());
}

Prevention

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

When it happens

Trigger: Running a db write subcommand (without --dry-run) while the pid file at paths.getPidFile() exists and paths.agentRunning() is true.

Common situations: 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.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/ec146d36353a833c. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-edge-agent/seatunnel-edge-agent-starter/src/main/java/org/apache/seatunnel/edge/agent/starter/command/db/DbWriteGuard.java:29

 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.seatunnel.edge.agent.starter.command.db;

import org.apache.seatunnel.edge.agent.starter.command.EdgeAgentPaths;

import java.io.IOException;

public class DbWriteGuard {

    public static void requireWriteAllowed(EdgeAgentPaths paths, DbCommandArgs cli)
            throws IOException {
        if (!cli.isDryRun() && paths.agentRunning()) {
            throw new IllegalStateException(
                    "Agent is running (pid file "
                            + paths.getPidFile()
                            + "); stop the agent before write operations.");
        }
        if (!cli.isDryRun() && !cli.isYes()) {
            throw new IllegalArgumentException("Write operations require --yes (or use --dry-run)");
        }
    }
}

View on GitHub (pinned to cf67b549a7)