apache/beam · error · ValueError

Vocabulary file {} not found in artifact location

Error message

Vocabulary file {} not found in artifact location

What it means

ArtifactFetchingService.get_vocab_list looks up a vocabulary by name via TFTransformOutput.vocabulary_by_name; when the underlying vocabulary file is absent, a ValueError is re-raised with a clearer message. It means the named vocab was not produced/saved into the artifact location.

Source

Thrown at sdks/python/apache_beam/ml/transforms/utils.py:81

    # TODO: https://github.com/apache/beam/issues/29356
    #  Integrate ArtifactFetcher into MLTransform.
    if len(files) > 1:
      raise NotImplementedError(
          "MLTransform may have been utilized alongside transforms written "
          "in TensorFlow Transform, in conjunction with those from different "
          "frameworks. Currently, retrieving artifacts from this "
          "multi-framework setup is not supported.")
    self._artifact_location = os.path.join(artifact_location, files[0])
    self.transform_output = tft.TFTransformOutput(self._artifact_location)

  def get_vocab_list(self, vocab_filename: str) -> list[bytes]:
    """
    Returns list of vocabulary terms created during MLTransform.
    """
    try:
      vocab_list = self.transform_output.vocabulary_by_name(vocab_filename)
    except ValueError as e:
      raise ValueError(
          'Vocabulary file {} not found in artifact location'.format(
              vocab_filename)) from e
    return [x.decode('utf-8') for x in vocab_list]

  def get_vocab_filepath(self, vocab_filename: str) -> str:
    """
    Return the path to the vocabulary file created during MLTransform.
    """
    return self.transform_output.vocabulary_file_by_name(vocab_filename)

  def get_vocab_size(self, vocab_filename: str) -> int:
    return self.transform_output.vocabulary_size_by_name(vocab_filename)

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass the exact vocab filename used by the transform (matches the name given to ComputeAndApplyVocabulary).
2. Verify the artifact location contains the *.vocabulary files before calling get_vocab_list.
3. Re-run the pipeline so artifacts are written, and ensure artifact_uri points at the correct run's output.

Example fix

# before
vocab = fetcher.get_vocab_list('user_vocab')
# after
import os
assert any('user_vocab' in f for f in os.listdir(fetcher._artifact_location))
vocab = fetcher.get_vocab_list('user_vocab')

import os
expected = os.path.join(artifact_location_dir, vocab_filename + '.vocabulary')
if not os.path.exists(expected): raise FileNotFoundError(expected)

try:
    vocab = fetcher.get_vocab_list(name)
except ValueError as e:
    logging.error('vocab %r missing from artifacts; check transform name', name)
    raise

When it happens

Trigger: Calling fetcher.get_vocab_list('my_vocab') where 'my_vocab.vocabulary' does not exist in the artifact directory — e.g. wrong vocab_filename, or the transform creating the vocabulary did not run/persist artifacts.

Common situations: Typo in the vocabulary name, artifacts from a different run, or using get_vocab_list for a transform (like scale transforms) that produces no vocabulary.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• src and dst files do not exist. src: %s, dst: %s
• Artifacts not found at location: %s when using read_artifact
• MLTransform may have been utilized alongside transforms writ
• The file %s cannot be found. It was specified in the --extra
• The feature store yaml path (%s) does not exist.

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