{"record":{"id":"d4889d92140fef8c","repo":"apache/beam","slug":"cannot-create-a-temporary-directory-for-root-path-prefix-s","errorCode":null,"errorMessage":"Cannot create a temporary directory for root path prefix %s. Please specify a file path prefix with at least two components.","messagePattern":"Cannot create a temporary directory for root path prefix (.+?)\\. Please specify a file path prefix with at least two components\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/filebasedsink.py","lineNumber":193,"sourceCode":"    \"\"\"\n    if file_handle is not None:\n      file_handle.close()\n\n  @check_accessible(['file_path_prefix', 'file_name_suffix'])\n  def initialize_write(self):\n    file_path_prefix = self.file_path_prefix.get()\n\n    tmp_dir = self._create_temp_dir(file_path_prefix)\n    FileSystems.mkdirs(tmp_dir)\n    return tmp_dir\n\n  def _create_temp_dir(self, file_path_prefix):\n    base_path, last_component = FileSystems.split(file_path_prefix)\n    if not last_component:\n      # Trying to re-split the base_path to check if it's a root.\n      new_base_path, _ = FileSystems.split(base_path)\n      if base_path == new_base_path:\n        raise ValueError(\n            'Cannot create a temporary directory for root path '\n            'prefix %s. Please specify a file path prefix with '\n            'at least two components.' % file_path_prefix)\n    path_components = [\n        base_path, 'beam-temp-' + last_component + '-' + uuid.uuid1().hex\n    ]\n    return FileSystems.join(*path_components)\n\n  @check_accessible(['file_path_prefix', 'file_name_suffix'])\n  def open_writer(self, init_result, uid):\n    # A proper suffix is needed for AUTO compression detection.\n    # We also ensure there will be no collisions with uid and a\n    # (possibly unsharded) file_path_prefix and a (possibly empty)\n    # file_name_suffix.\n    from apache_beam.pvalue import EmptySideInput\n\n    # Handle case where init_result is EmptySideInput (empty collection)\n    # TODO: https://github.com/apache/beam/issues/36563 for Prism","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/filebasedsink.py#L175-L211","documentation":"FileBasedSink._create_temp_dir builds a temporary staging directory next to the output prefix ('beam-temp-<last>-<uuid>'). If file_path_prefix is a bare root (e.g. '/', 'gs://bucket') it has no last component to build the directory name from, so a ValueError is raised asking for a prefix with at least two path components.","triggerScenarios":"Writing with a file_path_prefix like '/', 'gs://bucket/', or otherwise a single root component with no file name part; FileSystems.split yields an empty last_component and re-splitting the base path does not change it.","commonSituations":"Users point WriteToText at just a bucket/directory instead of a file prefix such as 'gs://bucket/output/data'.","solutions":["Append a file name prefix to the path, e.g. 'gs://my-bucket/output/data-'","Ensure the prefix has at least a directory and a file name component separated by '/'","Check the value passed to WriteToText/file_path_prefix for trailing-slash-only paths"],"exampleFix":"// before\nWriteToText('gs://my-bucket/')\n// after\nWriteToText('gs://my-bucket/output/results')","handlingStrategy":"validation","validationCode":"base, last = FileSystems.split(file_path_prefix)\nif not last:\n    raise ValueError(f'file_path_prefix needs a file name component: {file_path_prefix}')","typeGuard":"def has_file_component(prefix: str) -> bool:\n    from apache_beam.io.filesystems import FileSystems\n    return bool(FileSystems.split(prefix)[1])","tryCatchPattern":"try:\n    _ = beam.io.WriteToText(file_path_prefix)\nexcept ValueError as e:\n    if 'root path prefix' in str(e):\n        file_path_prefix = file_path_prefix.rstrip('/') + '/output/data'","preventionTips":["Always end output prefixes with a file name, not a directory or bucket root","Avoid trailing slashes on output paths","Test output prefixes against the target filesystem before launching jobs"],"tags":["python","apache-beam","io","path","configuration"],"backgroundTag":"invalid-argument-value","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"}