apache/beam · error · argparse.ArgumentError

The value ' ' in GCS custom audit entries exceeds the…

Error message

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

What it means

An argparse ArgumentError raised by the GCS custom audit entries option's _add_entry action: the value string supplied for a custom audit entry exceeds the maximum character length allowed per entry (MAX_KEY_LENGTH applies to keys, and this sibling guard applies to values). GCP enforces hard size limits on custom audit metadata, so the option rejects the value before it reaches the service.

Solutions

  1. Shorten or truncate the audit value to fit MAX_VALUE_LENGTH
  2. Move large payloads to GCS/a database and reference them with a short URL or ID in the audit value
  3. Pre-validate value length in code before setting the pipeline option

Example fix

// before
--gcs_custom_audit_entries=reason=<2000-char explanation>
// after
--gcs_custom_audit_entries=reason_id=run-12345
Defensive patterns

Strategy: validation

Validate before calling

if len(value) > _GcsCustomAuditEntriesAction.MAX_VALUE_LENGTH:
    value = value[:_GcsCustomAuditEntriesAction.MAX_VALUE_LENGTH]

Type guard

def is_valid_audit_value(value):
    return isinstance(value, str) and len(value) <= 800

Try / catch

try:
    parse_args(argv)
except argparse.ArgumentError as ex:
    print(f'audit value too long: {ex}')
    sys.exit(2)

Prevention

When it happens

Trigger: Passing a custom audit entry whose value string is longer than _GcsCustomAuditEntriesAction.MAX_VALUE_LENGTH, e.g. embedding a long JSON blob or URL as the value.

Common situations: Putting verbose context (stack traces, long descriptions, joined label sets) into audit values; building values programmatically from unbounded inputs.

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

Appendix: source

Thrown at sdks/python/apache_beam/options/pipeline_options.py:192

  def _exceed_entry_limit(self):
    job_audit_entry = _GcsCustomAuditEntriesAction.GCS_AUDIT_PREFIX + 'job'
    if job_audit_entry in self._custom_audit_entries:
      return len(
          self._custom_audit_entries) > _GcsCustomAuditEntriesAction.MAX_ENTRIES
    else:
      return len(self._custom_audit_entries) > (
          _GcsCustomAuditEntriesAction.MAX_ENTRIES - 1)

  def _add_entry(self, key, value):
    if len(key) > _GcsCustomAuditEntriesAction.MAX_KEY_LENGTH:
      raise argparse.ArgumentError(
          None,
          "The key '%s' in GCS custom audit entries exceeds the %d-character limit."  # pylint: disable=line-too-long
          % (key, _GcsCustomAuditEntriesAction.MAX_KEY_LENGTH))

    if len(value) > _GcsCustomAuditEntriesAction.MAX_VALUE_LENGTH:
      raise argparse.ArgumentError(
          None,
          "The value '%s' in GCS custom audit entries exceeds the %d-character limit."  # pylint: disable=line-too-long
          % (value, _GcsCustomAuditEntriesAction.MAX_VALUE_LENGTH))

    if key.startswith(_GcsCustomAuditEntriesAction.GCS_AUDIT_PREFIX):
      self._custom_audit_entries[key] = value
    else:
      self._custom_audit_entries[_GcsCustomAuditEntriesAction.GCS_AUDIT_PREFIX +
                                 key] = value

  def __call__(self, parser, namespace, values, option_string=None):
    if not hasattr(namespace, self.dest) or getattr(namespace,
                                                    self.dest) is None:
      setattr(namespace, self.dest, {})
      self._custom_audit_entries = getattr(namespace, self.dest)

    if option_string == '--gcs_custom_audit_entries':
      # in the format of {"key": "value"}

View on GitHub (pinned to 12126d8942)