apache/cassandra · error · IllegalArgumentException

You need to state at least one --target host to replay the q

Error message

You need to state at least one --target host to replay the query against

What it means

Replay.run requires at least one --target host to replay recorded queries against; with an empty target list it throws IllegalArgumentException. Comparing query results across replayed hosts is the core purpose of the tool, so at least one target is mandatory.

Source

Thrown at tools/fqltool/src/org/apache/cassandra/fqltool/commands/Replay.java:92

    public void run()
    {
        try
        {
            List<File> resultPaths = null;
            if (resultPath != null)
            {
                File basePath = new File(resultPath);
                if (!basePath.exists() || !basePath.isDirectory())
                {
                    System.err.println("The results path (" + basePath + ") should be an existing directory");
                    throw new IllegalArgumentException("The results path (" + basePath + ") should be an existing directory");
                }
                resultPaths = targetHosts.stream().map(target -> new File(basePath, target)).collect(Collectors.toList());
                resultPaths.forEach(File::mkdir);
            }
            if (targetHosts.size() < 1)
            {
                throw new IllegalArgumentException("You need to state at least one --target host to replay the query against");
            }
            replay(keyspace, arguments, targetHosts, resultPaths, queryStorePath, replayDDLStatements);
        }
        catch (Exception e)
        {
            throw new RuntimeException(e);
        }
    }

    public static void replay(String keyspace, List<String> arguments, List<String> targetHosts, List<File> resultPaths, String queryStorePath, boolean replayDDLStatements)
    {
        int readAhead = 200; // how many fql queries should we read in to memory to be able to sort them?
        List<ChronicleQueue> readQueues = null;
        List<FQLQueryIterator> iterators = null;
        List<Predicate<FQLQuery>> filters = new ArrayList<>();

        if (keyspace != null)
            filters.add(fqlQuery -> fqlQuery.keyspace() == null || fqlQuery.keyspace().equals(keyspace));

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add at least one --target host:port to the command line
2. Check the calling script for variables that expand to empty

Example fix

// before
fqltool replay --log_path log.bin --results /tmp/r
// after
fqltool replay --log_path log.bin --results /tmp/r --target 127.0.0.1:9042

function validateArgs(args) {
  const targets = [].concat(args.target || []);
  if (targets.length < 1) throw new Error('at least one --target host is required');
}

const hasTargets = args => Array.isArray(args.target) && args.target.length > 0;

try { runReplay(args); } catch (IllegalArgumentException e) { if (e.getMessage().contains("--target host")) { usage("specify --target host:port at least once"); } else throw e; }

When it happens

Trigger: Running fqltool replay without the --target option or with an empty list.

Common situations: Omitting --target in scripts; shell expansion producing an empty argument list.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid default spec:
• Must specify at least one command with a non-zero ratio
• Must specify at least one command with a non-zero ratio
• Invalid data rate: value must be non-negative
• Invalid data storage: %s Accepted units:%s

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/b6c1170ca388acda. Report an issue: GitHub.