apache/beam · error · RuntimeException

Could not parse the provided Transform Service config file…

Error message

Could not parse the provided Transform Service config file + configFile

What it means

Thrown by TransformServiceOptions.create when TransformServiceConfig.parseFromYamlStream raises FileNotFoundException while reading the config file (FileNotFoundException is an IOException, caught first). Practically this happens on a TOCTOU race or permission/unreadable-path issue where File.exists() returned true but opening failed.

Solutions

Confirm the path is a regular file with read permissions (ls -l, not a directory).
Check nothing is concurrently deleting or renaming the file.
Re-run; if transient, add existence+readability validation before constructing pipeline options.

Example fix

// before
File configFileObj = new File(configFile);
if (!configFileObj.exists()) { ... }
// after
File configFileObj = new File(configFile);
if (!configFileObj.isFile() || !configFileObj.canRead()) {
  throw new IllegalArgumentException("Config file not readable: " + configFile);
}

Defensive patterns

Strategy: validation

Validate before calling

static void requireReadableFile(String path) {
  File f = new File(path);
  if (!f.isFile()) throw new IllegalArgumentException("Not a regular file: " + path);
  if (!f.canRead()) throw new IllegalArgumentException("No read permission: " + path);
}

Try / catch

try {
  config = TransformServiceConfig.from(options);
} catch (RuntimeException e) {
  if (e.getCause() instanceof FileNotFoundException) {
    throw new IllegalStateException("Config file disappeared or is unreadable: "
        + options.as(TransformServiceOptions.class).getTransformServiceConfigFile(), e);
  }
  throw e;
}

Prevention

Ensure no cleanup job deletes config files while the pipeline starts.
Point to a regular file, never a directory.
Set correct file permissions for the user running the pipeline.

When it happens

Trigger: The config file is deleted or renamed between the exists() check and new FileInputStream(); the path is a directory; permission denied surfaces as IOException on some platforms.

Common situations: File removed concurrently by another process/cleanup job; pointing at a directory rather than a file; restrictive permissions.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/transform-service/src/main/java/org/apache/beam/sdk/transformservice/TransformServiceOptions.java:62

  TransformServiceConfig getTransformServiceConfig();

  void setTransformServiceConfig(TransformServiceConfig configFile);

  /** Loads the TransformService config. */
  class TransformServiceConfigFactory implements DefaultValueFactory<TransformServiceConfig> {

    @Override
    public TransformServiceConfig create(PipelineOptions options) {
      String configFile = options.as(TransformServiceOptions.class).getTransformServiceConfigFile();
      if (configFile != null) {
        File configFileObj = new File(configFile);
        if (!configFileObj.exists()) {
          throw new IllegalArgumentException("Config file " + configFile + " does not exist");
        }
        try (InputStream stream = new FileInputStream(configFileObj)) {
          return TransformServiceConfig.parseFromYamlStream(stream);
        } catch (FileNotFoundException e) {
          throw new RuntimeException(
              "Could not parse the provided Transform Service config file " + configFile, e);
        } catch (IOException e) {
          throw new RuntimeException(
              "Could not parse the provided Transform Service config file " + configFile, e);
        }
      }

      return TransformServiceConfig.empty();
    }
  }
}

View on GitHub (pinned to 12126d8942)