apache/beam · error · IllegalArgumentException

The key '%s' in GCS custom audit entries exceeds the %d-char

Error message

The key '%s' in GCS custom audit entries exceeds the %d-character limit.

What it means

GcsOptions.GcsCustomAuditEntries is a bounded map of GCS request-header audit entries; put() throws IllegalArgumentException when the key exceeds MAX_KEY_LENGTH (30 chars). Keys are namespaced with the x-goo-custom-audit-job prefix template.

Source

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

    private static final int MAX_ENTRIES = 4;

    private static final String CUSTOM_AUDIT_ENTRY_TMPL = "x-goog-custom-audit-%s";

    public static final String CUSTOM_AUDIT_JOB_ENTRY_KEY =
        String.format(CUSTOM_AUDIT_ENTRY_TMPL, "job");

    boolean exceedsEntryLimit() {
      if (this.containsKey(CUSTOM_AUDIT_JOB_ENTRY_KEY)) {
        return this.size() > MAX_ENTRIES;
      }

      return this.size() > MAX_ENTRIES - 1;
    }

    @Override
    public @Nullable String put(String key, String value) {
      if (key.length() > MAX_KEY_LENGTH) {
        throw new IllegalArgumentException(
            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()) {

View on GitHub (pinned to 12126d8942)

Solutions

Shorten the custom audit key to within MAX_KEY_LENGTH (30 characters)
Move long data into the value instead of the key
Hash or truncate the identifier before using it as a key
Check MAX_KEY_LENGTH in GcsOptions and validate user-supplied keys at pipeline-arg parsing time

Example fix

// before
gcsOptions.getGcsCustomAuditEntries().put("job-namespace-very-long-key-id-12345", "v");
// after
gcsOptions.getGcsCustomAuditEntries().put("job-key-12345", "v"); // <= 30 chars

Defensive patterns

Strategy: validation

Validate before calling

void safePut(GcsOptions.GcsCustomAuditEntries entries, String key, String value) {
  if (key.length() > 30) throw new IllegalArgumentException("audit key too long: " + key);
  entries.put(key, value);
}

Type guard

boolean validAuditKey(String k) { return k != null && k.length() <= 30; }

Try / catch

try {
  entries.put(key, value);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("exceeds the") && e.getMessage().contains("key")) {
    key = key.substring(0, 30); entries.put(key, value);
  } else throw e;
}

Prevention

Keep custom audit keys <= 30 characters
Truncate/hash identifiers before using them as keys
Add a unit test asserting key lengths from user config
Read MAX_KEY_LENGTH from GcsOptions rather than hardcoding

When it happens

Trigger: Calling put(key, value) on options.as(GcsOptions.class).getGcsCustomAuditEntries() with a key longer than MAX_KEY_LENGTH, before the prefix is applied.

Common situations: Passing long custom audit keys (e.g. full trace IDs or URLs) via pipeline options for header propagation to GCS; test code injecting oversized 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/4ab2f4e3cd2d9cde. Report an issue: GitHub.