apache/cassandra · error · IllegalArgumentException

Unrecognised insert option(s)

Error message

Unrecognised insert option(s): ${insert}

What it means

getInsert parses per-insert options from the YAML/insert spec. Recognized keys are consumed (e.g. batchtype); any remaining keys cause this IllegalArgumentException listing the leftovers. It rejects unknown insert options to surface config mistakes immediately.

Solutions

1. Remove or rename the unrecognized keys listed in the message; check supported insert options for this Cassandra version (visits, partitions, selectchance, batchtype, ...)
2. Fix common typos (batchtype vs batchtype casing/keys)
3. Cross-check the option names against the version's documentation or OptionInsert help
4. Test with a minimal insert spec, then add options incrementally

Example fix

# before
insert:
  batch: LOGGED
# after
insert:
  batchtype: LOGGED

// allow only supported insert option keys
Set<String> allowed = Set.of("partitions","selectchance","batchtype","visits","ratelimit","threads","rows");
insert.keySet().forEach(k -> { if (!allowed.contains(k)) throw new IllegalArgumentException("bad insert option: " + k); });

try { profile.getInsert(...); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unrecognised insert option")) log.error("Remove/rename: {}", e.getMessage()); throw e; }

When it happens

Trigger: Calling getInsert with settings/spec containing insert options other than the supported ones (partitions, selectchance, batchtype, visits, etc.), e.g. misspelled 'batch' instead of 'batchtype' or unsupported keys like 'row-count'.

Common situations: Older/other-version option names (option names changed across Cassandra releases), typos, mixing 'user profile' insert options with legacy cassandra-stress insert options.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Missing name argument in column spec
• No bulk read query defined with name
• No query defined with name
• Unrecognised option(s) in column spec
• Config contains both old and new keys for the same…

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

Appendix: source

Thrown at tools/stress/src/org/apache/cassandra/stress/StressProfile.java:663

                        {
                            sb.append(quoteIdentifier(c.getName())).append(", ");
                            value.append("?, ");
                        }
                        sb.delete(sb.lastIndexOf(","), sb.length());
                        value.delete(value.lastIndexOf(","), value.length());
                        sb.append(") ").append("values(").append(value).append(')');
                    }

                    partitions = select(settings.insert.batchsize, "partitions", "fixed(1)", insert, OptionDistribution.BUILDER);
                    selectchance = select(settings.insert.selectRatio, "select", "fixed(1)/1", insert, OptionRatioDistribution.BUILDER);
                    rowPopulation = select(settings.insert.rowPopulationRatio, "row-population", "fixed(1)/1", insert, OptionRatioDistribution.BUILDER);
                    batchType = settings.insert.batchType != null
                                ? settings.insert.batchType
                                : !insert.containsKey("batchtype")
                                  ? BatchStatement.Type.LOGGED
                                  : BatchStatement.Type.valueOf(insert.remove("batchtype"));
                    if (!insert.isEmpty())
                        throw new IllegalArgumentException("Unrecognised insert option(s): " + insert);

                    Distribution visits = settings.insert.visits.get();
                    // these min/max are not absolutely accurate if selectchance < 1, but they're close enough to
                    // guarantee the vast majority of actions occur in these bounds
                    double minBatchSize = selectchance.get().min() * partitions.get().minValue() * generator.minRowCount * (1d / visits.maxValue());
                    double maxBatchSize = selectchance.get().max() * partitions.get().maxValue() * generator.maxRowCount * (1d / visits.minValue());

                    if (generator.maxRowCount > 100 * 1000 * 1000)
                        System.err.printf("WARNING: You have defined a schema that permits very large partitions (%.0f max rows (>100M))%n", generator.maxRowCount);
                    if (batchType == BatchStatement.Type.LOGGED && maxBatchSize > 65535)
                    {
                        System.err.printf("ERROR: You have defined a workload that generates batches with more than 65k rows (%.0f), but have required the use of LOGGED batches. There is a 65k row limit on a single batch.%n",
                                          selectchance.get().max() * partitions.get().maxValue() * generator.maxRowCount);
                        System.exit(1);
                    }
                    if (maxBatchSize > 100000)
                        System.err.printf("WARNING: You have defined a schema that permits very large batches (%.0f max rows (>100K)). This may OOM this stress client, or the server.%n",
                                          selectchance.get().max() * partitions.get().maxValue() * generator.maxRowCount);

View on GitHub (pinned to 88fd0f6a0e)