{"record":{"id":"7a3c4877f9a1ca65","repo":"apache/beam","slug":"a-pubsub-message-attribute-key-must-not-exceed-256-bytes","errorCode":null,"errorMessage":"A pubsub message attribute key must not exceed 256 bytes.","messagePattern":"A pubsub message attribute key must not exceed 256 bytes\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/gcp/pubsub.py","lineNumber":162,"sourceCode":"      for_publish: bool, if True strip out message fields which cannot be\n        published (currently message_id and publish_time) per\n        https://cloud.google.com/pubsub/docs/reference/rpc/google.pubsub.v1#pubsubmessage\n\n    Returns:\n      A str containing a serialized protobuf of type\n      https://cloud.google.com/pubsub/docs/reference/rpc/google.pubsub.v1#google.pubsub.v1.PubsubMessage\n      containing the payload of this object.\n    \"\"\"\n    if len(self.data) > (10_000_000):\n      raise ValueError('A pubsub message data field must not exceed 10MB')\n\n    if self.attributes:\n      if len(self.attributes) > 100:\n        raise ValueError(\n            'A pubsub message must not have more than 100 attributes.')\n      for key, value in self.attributes.items():\n        if len(key) > 256:\n          raise ValueError(\n              'A pubsub message attribute key must not exceed 256 bytes.')\n        if len(value) > 1024:\n          raise ValueError(\n              'A pubsub message attribute value must not exceed 1024 bytes')\n\n    message_id = None\n    publish_time = None\n    if not for_publish:\n      if self.message_id:\n        message_id = self.message_id\n        if self.publish_time:\n          publish_time = self.publish_time\n\n    if len(self.ordering_key) > 1024:\n      raise ValueError(\n          'A pubsub message ordering key must not exceed 1024 bytes.')\n\n    msg = pubsub.types.PubsubMessage(","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/gcp/pubsub.py#L144-L180","documentation":"PubsubMessage._to_proto_str enforces the Cloud Pub/Sub limit that attribute keys be at most 256 bytes; one of the keys in self.attributes exceeds it, so serialization is aborted before the API rejects the message.","triggerScenarios":"Calling message_to_proto_str / _to_proto_str where any key in self.attributes has len(key) > 256.","commonSituations":"Using long identifiers, full URLs, or concatenated names as attribute keys; attributes derived from untrusted/user-supplied header names.","solutions":["Shorten the attribute key (e.g. use a short token and put the full value in the message body).","Hash or truncate long keys before constructing PubsubMessage.","Move long key-value metadata into the data payload (JSON) instead of attributes."],"exampleFix":"// before\nattrs[full_url] = 'true'  # key > 256 bytes\n// after\nattrs['source_url_sha'] = hashlib.sha256(full_url.encode()).hexdigest()[:32]","handlingStrategy":"validation","validationCode":"bad = [k for k in (attributes or {}) if len(k) > 256]\nif bad:\n    raise ValueError(f'attribute keys exceed 256 bytes: {bad[:3]}')","typeGuard":"def has_valid_attribute_keys(attrs):\n    return not attrs or all(len(k) <= 256 for k in attrs)","tryCatchPattern":"try:\n    proto = PubsubMessage(data=data, attributes=attrs)._to_proto_str()\nexcept ValueError as e:\n    if 'attribute key must not exceed 256' in str(e):\n        log.error('Shorten or hash oversized attribute keys')\n    raise","preventionTips":["Use short token keys, not URLs or long identifiers","Sanitize user-supplied header names before mapping to attributes","Add a key-length check in your message builder helper"],"tags":["pubsub","attributes","size-limit","python","apache-beam"],"backgroundTag":"payload-too-large","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}