apache/beam · error · TypeError

file_path_prefix must be a string or ValueProvider;got %r…

Error message

file_path_prefix must be a string or ValueProvider;got %r instead

What it means

FileBasedSink's constructor requires file_path_prefix to be either a str or a runtime ValueProvider; anything else (bytes, pathlib.Path, None, int) raises TypeError with this message. This ensures the sink works both at construction time and during pipeline translation where templates resolve values dynamically.

Solutions

Convert with str(file_path_prefix) before constructing the sink
Wrap dynamic values in apache_beam.options.value_provider.StaticValueProvider or RuntimeValueProvider
Validate the prefix type at config-load time

Example fix

// before
sink = WriteToText(Path('/out/results'), shard_name_template='-SSS-of-NNN')
// after
sink = WriteToText(str(Path('/out/results')), shard_name_template='-SSS-of-NNN')

Defensive patterns

Strategy: type-guard

Validate before calling

if not isinstance(file_path_prefix, (str, ValueProvider)):
    file_path_prefix = str(file_path_prefix)

Type guard

from apache_beam.options.value_provider import ValueProvider
def is_valid_path_prefix(p):
    return isinstance(p, (str, ValueProvider)) and bool(p)

Try / catch

try:
    sink = WriteToText(file_path_prefix, ...)
except TypeError as e:
    if 'file_path_prefix' in str(e):
        sink = WriteToText(str(file_path_prefix), ...)
    else:
        raise

Prevention

Cast pathlib.Path to str at config boundaries
Keep template-driven values as ValueProvider, not other types
Validate sink arguments when loading pipeline options

When it happens

Trigger: Passing pathlib.Path, bytes from os.fsencode, or None as file_path_prefix to WriteToText/CustomSink; computing the prefix into a non-string object in a dataflow template.

Common situations: Using Path objects from pathlib for 'modern' style; str.format mistakes yielding non-str; config parsed as bytes.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/acebcac667e8ec9d. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/io/filebasedsink.py:90

      mime_type='application/octet-stream',
      compression_type=CompressionTypes.AUTO,
      *,
      max_records_per_shard=None,
      max_bytes_per_shard=None,
      skip_if_empty=False,
      convert_fn=None,
      triggering_frequency=None):
    """
     Raises:
      TypeError: if file path parameters are not a :class:`str` or
        :class:`~apache_beam.options.value_provider.ValueProvider`, or if
        **compression_type** is not member of
        :class:`~apache_beam.io.filesystem.CompressionTypes`.
      ValueError: if **shard_name_template** is not of expected
        format.
    """
    if not isinstance(file_path_prefix, (str, ValueProvider)):
      raise TypeError(
          'file_path_prefix must be a string or ValueProvider;'
          'got %r instead' % file_path_prefix)
    if not isinstance(file_name_suffix, (str, ValueProvider)):
      raise TypeError(
          'file_name_suffix must be a string or ValueProvider;'
          'got %r instead' % file_name_suffix)

    if not CompressionTypes.is_valid_compression_type(compression_type):
      raise TypeError(
          'compression_type must be CompressionType object but '
          'was %s' % type(compression_type))
    if shard_name_template is None:
      shard_name_template = DEFAULT_SHARD_NAME_TEMPLATE
    elif shard_name_template == '':
      num_shards = 1
    if triggering_frequency is None:
      triggering_frequency = DEFAULT_TRIGGERING_FREQUENCY
    if isinstance(file_path_prefix, str):

View on GitHub (pinned to 12126d8942)