apache/beam · error · argparse.ArgumentError

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

Error message

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

What it means

This argparse action validates GCS custom audit entry keys passed via pipeline options. It raises when a key exceeds the maximum allowed key length, since GCS audit metadata has hard character limits enforced upstream.

Solutions

Shorten the audit entry key to within MAX_KEY_LENGTH characters
Check the key length before constructing the option and raise a friendlier error or truncate
Use a shorter alias key and keep the long form in the value if the value limit allows

Example fix

// before
--gcs_custom_audit_entries=very_long_team_department_cost_center_key=value
// after
--gcs_custom_audit_entries=team_key=value

Defensive patterns

Strategy: validation

Validate before calling

if len(key) > _GcsCustomAuditEntriesAction.MAX_KEY_LENGTH:
    key = key[:_GcsCustomAuditEntriesAction.MAX_KEY_LENGTH]

Type guard

def is_valid_audit_key(key):
    return isinstance(key, str) and 0 < len(key) <= 80

Try / catch

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

Prevention

Pre-truncate keys before building CLI args
Keep audit keys short and identifier-like
Add length checks in code that generates audit entries

When it happens

Trigger: Calling the GCS custom audit entries option (e.g. --gcs_custom_audit_entries or setting custom audit via PipelineOption) with a key longer than _GcsCustomAuditEntriesAction.MAX_KEY_LENGTH.

Common situations: Copy-pasting verbose audit metadata keys from another system; programmatically building audit keys from long identifiers; typo concatenating key=value pairs.

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

Appendix: source

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

  - a maximum of four custom metadata entries are permitted per request.
  """
  MAX_KEY_LENGTH = 64
  MAX_VALUE_LENGTH = 1200
  MAX_ENTRIES = 4
  GCS_AUDIT_PREFIX = 'x-goog-custom-audit-'

  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,

View on GitHub (pinned to 12126d8942)