{"record":{"id":"02e41040db876327","repo":"apache/beam","slug":"checksum-operation-failed-gcsfilesystem","errorCode":null,"errorMessage":"Checksum operation failed","messagePattern":"Checksum operation failed","errorType":"exception","errorClass":"BeamIOError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/gcp/gcsfilesystem.py","lineNumber":325,"sourceCode":"    \"\"\"\n    return self._gcsIO().last_updated(path)\n\n  def checksum(self, path):\n    \"\"\"Fetch checksum metadata of a file on the\n    :class:`~apache_beam.io.filesystem.FileSystem`.\n\n    Args:\n      path: string path of a file.\n\n    Returns: string containing checksum\n\n    Raises:\n      ``BeamIOError``: if path isn't a file or doesn't exist.\n    \"\"\"\n    try:\n      return self._gcsIO().checksum(path)\n    except Exception as e:  # pylint: disable=broad-except\n      raise BeamIOError(\"Checksum operation failed\", {path: e})\n\n  def metadata(self, path):\n    \"\"\"Fetch metadata fields of a file on the FileSystem.\n\n    Args:\n      path: string path of a file.\n\n    Returns:\n      :class:`~apache_beam.io.filesystem.FileMetadata`.\n\n    Raises:\n      ``BeamIOError``: if path isn't a file or doesn't exist.\n    \"\"\"\n    try:\n      file_metadata = self._gcsIO()._status(path)\n      return FileMetadata(path, file_metadata['size'], file_metadata['updated'])\n    except Exception as e:  # pylint: disable=broad-except\n      raise BeamIOError(\"Metadata operation failed\", {path: e})","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/gcp/gcsfilesystem.py#L307-L343","documentation":"GcsFileSystem.checksum wraps gcsio.checksum and raises BeamIOError('Checksum operation failed') whenever the underlying call throws, e.g. because the path is not a file or does not exist. The original error is stored in exception_details keyed by path.","triggerScenarios":"Calling GcsFileSystem.checksum(path) on a path that doesn't exist, is a directory/prefix, or where the GCS API call fails (permissions, network).","commonSituations":"Computing checksums of output files deleted by retention policies; passing a directory prefix instead of a single object path; typo'd object name.","solutions":["Verify the path exists and is a file (filesystem.match/exists) before calling checksum.","Check the wrapped error in exception_details for the root cause.","Correct the gs:// path (bucket + full object name).","Catch BeamIOError and treat missing objects as empty/absent checksums if appropriate."],"exampleFix":"// before\ncrc = fs.checksum(path)\n// after\nif fs.exists(path):\n  crc = fs.checksum(path)\nelse:\n  crc = None","handlingStrategy":"validation","validationCode":"if not fs.exists(path):\n    raise FileNotFoundError(path)","typeGuard":"def valid_gcs_path(p):\n    return isinstance(p, str) and p.startswith('gs://') and p.count('/') >= 3","tryCatchPattern":"try:\n    crc = fs.checksum(path)\nexcept BeamIOError as e:\n    logging.warning('checksum failed: %s', e.exception_details.get(path))\n    crc = None","preventionTips":["Confirm the path is a single object, not a prefix","Check existence before checksum","Guard against lifecycle-driven deletion between write and read"],"tags":["gcs","checksum","io"],"backgroundTag":"file-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}