apache/beam · error · RuntimeException

SolaceIO.Write: Trying to create a batch of

Error message

SolaceIO.Write: Trying to create a batch of ${records.size()}, but Solace supports a maximum of ${SOLACE_BATCH_LIMIT}. The batch will likely be rejected by Solace.

What it means

SolaceIO.Write throws this RuntimeException in MessageProducerUtils.createJCSMPSendMultipleEntry when a caller tries to build a transacted batch of more records than Solace supports in a single send-multiple (SOLACE_BATCH_LIMIT). Solace brokers reject oversized transacted send batches, so the connector fails fast before publishing a batch that would be rejected.

Solutions

Reduce the writer's batch size configuration so each batch is <= SOLACE_BATCH_LIMIT.
Chunk the record list before calling createJCSMPSendMultipleEntry and send multiple smaller batches.
Check the SOLACE_BATCH_LIMIT constant in the connector version you use, since it caps batches at Solace's documented maximum.
If batches come from bundle size, lower the pipeline's bundle/flush sizing for the Write transform.

Example fix

// before
JCSMPSendMultipleEntry[] batch = MessageProducerUtils.createJCSMPSendMultipleEntry(allRecords, useLatency, destFn, DeliveryMode.PERSISTENT);
// after
for (List<Solace.Record> chunk : Lists.partition(allRecords, SOLACE_BATCH_LIMIT)) {
  JCSMPSendMultipleEntry[] batch = MessageProducerUtils.createJCSMPSendMultipleEntry(chunk, useLatency, destFn, DeliveryMode.PERSISTENT);
  producer.sendMultiple(batch);
}

Defensive patterns

Strategy: validation

Validate before calling

if (records.size() > SOLACE_BATCH_LIMIT) {
  throw new IllegalArgumentException("Batch of " + records.size() + " exceeds Solace limit " + SOLACE_BATCH_LIMIT);
}

Try / catch

try { producer.sendMultiple(entries); } catch (RuntimeException e) { if (e.getMessage().contains("maximum of")) { /* split batch and resend */ } throw e; }

Prevention

Keep writer batch-size config at or below Solace's transacted batch maximum
Use Lists.partition() to chunk large record lists before batching
Re-check SOLACE_BATCH_LIMIT when upgrading the connector or broker

When it happens

Trigger: Passing a `List<Solace.Record>` larger than the Solace batch limit (typically 50 messages) into `createJCSMPSendMultipleEntry(...)`, or configuring the Write transform so that buffered records per bundle/transaction exceed the limit.

Common situations: High-throughput writers with large batch-size configuration; grouping many elements in one bundle before flushing; using `withMaxBatchSize` (or equivalent) set above the broker's supported transacted batch limit.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/49d686aba1a3384e. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/solace/src/main/java/org/apache/beam/sdk/io/solace/broker/MessageProducerUtils.java:80

   * Create a {@link JCSMPSendMultipleEntry} array to be published in Solace. This can be used with
   * `sendMultiple` to send all the messages in a single API call.
   *
   * <p>The size of the list cannot be larger than 50 messages. This is a hard limit enforced by the
   * Solace API.
   *
   * @param records A {@link List} of records to be published
   * @param useCorrelationKeyLatency Whether to use a complex key for tracking latency.
   * @param destinationFn A function that maps every record to its destination.
   * @param deliveryMode The {@link DeliveryMode} used to publish the message.
   * @return A {@link JCSMPSendMultipleEntry} array that can be sent to Solace "as is".
   */
  public static JCSMPSendMultipleEntry[] createJCSMPSendMultipleEntry(
      List<Solace.Record> records,
      boolean useCorrelationKeyLatency,
      SerializableFunction<Solace.Record, Destination> destinationFn,
      DeliveryMode deliveryMode) {
    if (records.size() > SOLACE_BATCH_LIMIT) {
      throw new RuntimeException(
          String.format(
              "SolaceIO.Write: Trying to create a batch of %d, but Solace supports a"
                  + " maximum of %d. The batch will likely be rejected by Solace.",
              records.size(), SOLACE_BATCH_LIMIT));
    }

    JCSMPSendMultipleEntry[] entries = new JCSMPSendMultipleEntry[records.size()];
    for (int i = 0; i < records.size(); i++) {
      Solace.Record record = records.get(i);
      JCSMPSendMultipleEntry entry =
          JCSMPFactory.onlyInstance()
              .createSendMultipleEntry(
                  createMessage(record, useCorrelationKeyLatency, deliveryMode),
                  destinationFn.apply(record));
      entries[i] = entry;
    }

    return entries;

View on GitHub (pinned to 12126d8942)