apache/seatunnel · error · IllegalArgumentException

Write operations require --yes (or use --dry-run)

Error message

Write operations require --yes (or use --dry-run)

What it means

DbWriteGuard.requireWriteAllowed blocks any agent DB write operation unless the CLI was invoked with explicit confirmation. A write command is allowed only when --yes is passed (explicit intent) or --dry-run is used (no mutation). The exception is thrown as IllegalArgumentException before any DB connection is opened.

Solutions

1. Re-run with --dry-run first to preview affected rows, then re-run with --yes to apply.
2. If you only want a report, add --dry-run so the guard is satisfied without writing.
3. Stop the agent first if the pid-file check also fires, then re-run with --yes.
4. Update your scripts to pass --yes explicitly, never default it silently.

Example fix

// before
agent db wal-purge-acked --older-than-ms 86400000
// after
agent db wal-purge-acked --older-than-ms 86400000 --yes
// or preview first
agent db wal-purge-acked --older-than-ms 86400000 --dry-run

const args = process.argv.slice(2);
const isWriteCmd = /^(wal-purge-acked|wal-purge-dead|wal-retry-dead|wal-unstick-sending)$/.test(args[0]);
if (isWriteCmd && !args.includes('--yes') && !args.includes('--dry-run')) {
  throw new Error('Refusing to run write command without --yes or --dry-run');
}

try {
  runAgentDbCommand(args);
} catch (e) {
  if (String(e.message).includes('--yes')) {
    console.error('Confirmation required: re-run with --dry-run to preview, then --yes to apply.');
  }
}

When it happens

Trigger: Running a mutating wal subcommand (wal-purge-acked, wal-retry-dead, wal-purge-dead, wal-unstick-sending) without either --yes or --dry-run flags.

Common situations: Users run wal-purge-acked in CI/scripts and forget the confirmation flag; interactive users type commands from docs without the safety flag; scripts written before the guard was introduced now fail.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• Refusing write without --yes
• Agent is running (pid file ); stop the agent before write…
• Cluster name is required. Please specify it using -cn or…
• cluster: is not running, Please start the cluster first.
• Dry-run is only supported via CLI

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/afa7ead4252a8c69. 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:35

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)