apache/beam · error · IllegalArgumentException

The maximum allowed number of GCS custom audit entries…

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).

Solutions

Reduce the number of custom audit entries to stay within MAX_ENTRIES
Merge related dimensions into fewer, shorter entries
Drop low-value entries before put (check exceedsEntryLimit() yourself first)
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

Bound the number of audit entries you generate (MAX_ENTRIES includes the default one)
Merge related dimensions into fewer entries
Check size() before each put
Centralize audit-entry population in one audited helper

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.

Appendix: 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)