apache/beam · error · IllegalArgumentException

The maximum allowed number of GCS custom audit entries (incl

Error message

The maximum allowed number of GCS custom audit entries (including the default x-goo-custom-audit-job) is %d.

What it means

GcsCustomAuditEntries allows at most MAX_ENTRIES audit entries (including the default x-goo-custom-audit-job); put() that pushes the map past the limit throws IllegalArgumentException with this message after the entry was inserted (the put is not rolled back).

Source

Thrown at sdks/java/extensions/google-cloud-platform-core/src/main/java/org/apache/beam/sdk/extensions/gcp/options/GcsOptions.java:292

            String.format(
                "The key '%s' in GCS custom audit entries exceeds the %d-character limit.",
                key, MAX_KEY_LENGTH));
      }

      if (value.length() > MAX_VALUE_LENGTH) {
        throw new IllegalArgumentException(
            String.format(
                "The value '%s' in GCS custom audit entries exceeds the %d-character limit.",
                value, MAX_VALUE_LENGTH));
      }

      String prefix = CUSTOM_AUDIT_ENTRY_TMPL.substring(0, CUSTOM_AUDIT_ENTRY_TMPL.indexOf('%'));
      String formattedKey =
          key.startsWith(prefix) ? key : String.format(CUSTOM_AUDIT_ENTRY_TMPL, key);
      String oldValue = super.put(formattedKey, value);

      if (exceedsEntryLimit()) {
        throw new IllegalArgumentException(
            String.format(
                "The maximum allowed number of GCS custom audit entries (including the default x-goo-custom-audit-job) is %d.",
                MAX_ENTRIES));
      }

      return oldValue;
    }
  }
}

class GcsReadOptionsSerializer extends JsonSerializer<GoogleCloudStorageReadOptions> {
  static final GoogleCloudStorageReadOptions DEFAULT_OPTIONS =
      GoogleCloudStorageReadOptions.DEFAULT.toBuilder()
          .setFadvise(GoogleCloudStorageReadOptions.Fadvise.SEQUENTIAL)
          .build();

  @Override
  public void serialize(

View on GitHub (pinned to 12126d8942)

Solutions

  1. Reduce the number of custom audit entries to stay within MAX_ENTRIES
  2. Merge related dimensions into fewer, shorter entries
  3. Drop low-value entries before put (check exceedsEntryLimit() yourself first)
  4. Gate additions: if (entries.exceedsEntryLimit()) skip instead of adding

Example fix

// before
for (String k : manyKeys) entries.put(k, v); // exceeds limit
// after
int budget = MAX_ENTRIES - 1 - entries.size();
for (String k : manyKeys) { if (budget-- <= 0) break; entries.put(k, v); }
Defensive patterns

Strategy: validation

Validate before calling

// check capacity before adding
if (!entries.exceedsEntryLimit()) { /* safe to add one more */ entries.put(key, value); }

Try / catch

try {
  entries.put(key, value);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("maximum allowed number")) {
    // drop or merge an existing entry, then retry once
  } else throw e;
}

Prevention

When it happens

Trigger: Adding more than MAX_ENTRIES - 1 custom entries via put(); exceedsEntryLimit() returns true after super.put(formattedKey, value).

Common situations: Automatically populating audit entries per-tenant/per-dimension without bounding the count; repeated pipeline configurations accumulating keys.

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/5d75eaf8d3223dbc. Report an issue: GitHub.