{"record":{"id":"a398cf9e07f626ec","repo":"apache/beam","slug":"unable-to-get-filesystem-from-specified-path-please-use-the","errorCode":null,"errorMessage":"Unable to get filesystem from specified path, please use the correct path or ensure the required dependency is installed, e.g., pip install apache-beam[gcp]. Path specified: %s","messagePattern":"Unable to get filesystem from specified path, please use the correct path or ensure the required dependency is installed, e\\.g\\., pip install apache-beam\\[gcp\\]\\. Path specified: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/filesystems.py","lineNumber":139,"sourceCode":"    match_result = FileSystems.URI_SCHEMA_PATTERN.match(path.strip())\n    if match_result is None:\n      return None\n    return match_result.groupdict()['scheme']\n\n  @staticmethod\n  def get_filesystem(path):\n    # type: (str) -> FileSystem\n\n    \"\"\"Get the correct filesystem for the specified path\n    \"\"\"\n    try:\n      path_scheme = FileSystems.get_scheme(path)\n      systems = [\n          fs for fs in FileSystem.get_all_subclasses()\n          if fs.scheme() == path_scheme\n      ]\n      if len(systems) == 0:\n        raise ValueError(\n            'Unable to get filesystem from specified path, please use the '\n            'correct path or ensure the required dependency is installed, '\n            'e.g., pip install apache-beam[gcp]. Path specified: %s' % path)\n      elif len(systems) == 1:\n        # Pipeline options could come either from the Pipeline itself (using\n        # direct runner), or via RuntimeValueProvider (other runners).\n        options = (\n            FileSystems._pipeline_options or\n            RuntimeValueProvider.runtime_options)\n        return systems[0](pipeline_options=options)\n      else:\n        raise ValueError('Found more than one filesystem for path %s' % path)\n    except ValueError:\n      raise\n    except Exception as e:\n      raise BeamIOError('Unable to get the Filesystem', {path: e})\n\n  @staticmethod","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/filesystems.py#L121-L157","documentation":"FileSystems.get_filesystem(path) resolves the URL scheme (e.g. gs://, s3://, hdfs://) against all registered FileSystem subclasses; if none matches the path's scheme it raises ValueError telling the user to check the path or install the required dependency such as apache-beam[gcp]. Beam cannot route I/O for a scheme it has no implementation for.","triggerScenarios":"Calling FileSystems.get_filesystem('gs://bucket/obj') without the GCP extras installed; using a misspelled or missing scheme (e.g. 'gcs://bucket' instead of 'gs://', or a bare '/local/path' with no scheme where local_filesystem isn't registered).","commonSituations":"Installing plain apache-beam instead of apache-beam[gcp] and then reading GCS paths; forgetting extras like apache-beam[aws] for S3; typos in path schemes in pipeline options; custom filesystem plugin not imported/registered before use.","solutions":["Install the extra that provides the filesystem: pip install 'apache-beam[gcp]' (or [aws], [azure], as appropriate).","Fix the path so it uses a supported scheme, e.g. 'gs://bucket/path' not 'gcs://bucket/path'.","Verify the scheme is registered: check FileSystem.get_all_subclasses() and their .scheme() values.","For local files, use plain filesystem paths ('/tmp/x' or 'file:///tmp/x') rather than remote schemes.","If you wrote a custom FileSystem, ensure its module is imported (subclass registration happens at import time) and its scheme() matches the path prefix."],"exampleFix":"// before\npip install apache-beam\nFileSystems.get_filesystem('gs://bucket/data.csv')  # ValueError\n// after\npip install 'apache-beam[gcp]'\nFileSystems.get_filesystem('gs://bucket/data.csv')  # -> GCSFileSystem","handlingStrategy":"fallback","validationCode":"from urllib.parse import urlparse\nfrom apache_beam.io import FileSystem\nscheme = urlparse(path).scheme\nknown = {fs.scheme() for fs in FileSystem.get_all_subclasses()}\nif scheme not in known:\n    raise ValueError(f'no filesystem for scheme {scheme!r}; install the matching apache-beam extra')","typeGuard":null,"tryCatchPattern":"try:\n    fs = FileSystems.get_filesystem(path)\nexcept ValueError as e:\n    if 'Unable to get filesystem' in str(e):\n        raise RuntimeError(\n            f'{e}; install the right extra: pip install apache-beam[gcp|aws]'\n        ) from e\n    raise","preventionTips":["Install the extras you use: apache-beam[gcp], [aws], [azure].","Use canonical schemes: gs:// (not gcs://), s3://, hdfs://.","Verify scheme support early in job setup by calling FileSystems.get_filesystem on a sample path.","If using a custom FileSystem, import its module before first use (registration is at import time)."],"tags":["python","io","filesystem","scheme","missing-dependency"],"backgroundTag":"missing-optional-dependency","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-15T13:17:12.816Z"}