{"record":{"id":"4093e73538d07075","repo":"apache/beam","slug":"checksum-operation-failed-blobstoragefilesystem","errorCode":null,"errorMessage":"Checksum operation failed","messagePattern":"Checksum operation failed","errorType":"exception","errorClass":"BeamIOError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/azure/blobstoragefilesystem.py","lineNumber":280,"sourceCode":"    except Exception as e:  # pylint: disable=broad-except\n      raise BeamIOError(\"Last updated operation failed\", {path: e})\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._blobstorageIO().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._blobstorageIO()._status(path)\n      return FileMetadata(\n          path, file_metadata['size'], file_metadata['last_updated'])\n    except Exception as e:  # pylint: disable=broad-except","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/azure/blobstoragefilesystem.py#L262-L298","documentation":"BlobStorageFileSystem.checksum() fetches blob checksum metadata and re-raises any exception as BeamIOError('Checksum operation failed', {path, e}). Note the source uses a set literal {path, e} instead of the dict {path: e} used elsewhere — the exception details are still attached to the BeamIOError but the path-to-error mapping is malformed.","triggerScenarios":"Calling fs.checksum(path) on a path that is not a file or does not exist, or when the Azure SDK raises while fetching blob properties (auth, network, permissions).","commonSituations":"Pointing checksum verification at a directory-style (empty-prefix) path; blob deleted between discovery and checksum; missing read permissions; relying on the malformed exception-details mapping and expecting a dict.","solutions":["Verify the path points to an actual blob (not a directory-style prefix) with fs.exists / fs.metadata first","Inspect the BeamIOError details to identify the root Azure exception","Do not depend on exception_details being a {path: error} dict here due to the {path, e} set literal in the source","Check read permissions and credentials if the underlying error is authorization"],"exampleFix":"// before\ntry:\n    checksum = fs.checksum(path)\nexcept BeamIOError as e:\n    handle(e.exception_details)  # expects dict, gets a set\n// after\ntry:\n    checksum = fs.checksum(path)\nexcept BeamIOError as e:\n    logging.error(f\"checksum failed for {path}: {e!r}\")\n    raise","handlingStrategy":"try-catch","validationCode":"if not fs.exists(path):\n    raise FileNotFoundError(f\"no such blob: {path}\")\n# ensure it is a file, not a directory-style prefix\nmeta = fs.metadata(path)","typeGuard":null,"tryCatchPattern":"try:\n    checksum = fs.checksum(path)\nexcept BeamIOError as e:\n    logging.error(\"checksum failed for %s: %r\", path, e)\n    raise  # note: exception_details is a set here, not a dict","preventionTips":["Verify the path is a real blob, not a directory-style prefix","Do not rely on exception_details being a {path: error} dict for this method (source uses {path, e})","Check read permissions on the container","Pre-check existence to avoid missing-blob failures"],"tags":["python","apache-beam","azure-blob-storage","filesystem-io","error-wrapping"],"backgroundTag":"checksum-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}