apache/beam · error · IllegalArgumentException

The value '%s' in GCS custom audit entries exceeds the %d-ch

Error message

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

What it means

Same bounded map as above: put() throws IllegalArgumentException when the value exceeds MAX_VALUE_LENGTH (30 chars), because these values are serialized into GCS request headers with strict size limits.

Source

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

    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()) {
        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;

View on GitHub (pinned to 12126d8942)

Solutions

Shorten the value to fit MAX_VALUE_LENGTH (30 characters)
Truncate or hash long identifiers before storing
Split data across multiple entries within MAX_ENTRIES
Pre-validate value lengths when building the options map

Example fix

// before
entries.put("run", longJobName);
// after
entries.put("run", longJobName.substring(0, 30));

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Keep custom audit values <= 30 characters
Hash or truncate long job/trace identifiers
Validate values at config-parsing time
Add tests for value length limits

When it happens

Trigger: Calling put(key, value) on GcsCustomAuditEntries with a value longer than MAX_VALUE_LENGTH.

Common situations: Putting full job names, URLs, or JSON blobs as audit values; concatenating identifiers without checking length.

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/090162b7ca295d24. Report an issue: GitHub.