apache/beam · error · java.lang.RuntimeException

Could not parse the provided Expansion Service config file

Error message

Could not parse the provided Expansion Service config file

What it means

Wraps FileNotFoundException (or IOException) raised while opening/reading the expansion service config file in the config provider's create(). The message 'Could not parse the provided Expansion Service config file' plus path and cause replaces the raw IO exception with a contextual runtime exception.

Solutions

Confirm the file exists and is readable by the service user ('ls -lL', 'sudo -u svc cat <path>') and restart.
Replace broken symlinks with the real file path or fix the mount source.
Correct file permissions (chmod/chown) so the service process can read the config.
Inspect the wrapped cause for the underlying errno and address it (missing file vs permission denied).

Example fix

// before
config -> /etc/expansion/current.yaml  (symlink to rotated-away file)
// after
ls -lL /etc/expansion/current.yaml && java -jar expansion-service.jar --expansionServiceConfigFile=/etc/expansion/current.yaml

Defensive patterns

Strategy: try-catch

Validate before calling

File f = new File(configPath);
if (!f.isFile() || !f.canRead()) {
  throw new IllegalStateException("Config file not readable (symlink/permissions?): " + configPath);
}

Try / catch

try {
  startExpansionService(options);
} catch (RuntimeException e) {
  if (e.getCause() instanceof FileNotFoundException || e.getCause() instanceof IOException) { /* fix file/mount and retry */ }
  throw e;
}

Prevention

Avoid symlink chains to rotated files; re-point mounts atomically.
Grant read access to the service user on the config directory.
Log and inspect the wrapped cause to distinguish missing-file from permission issues.

When it happens

Trigger: The config file disappears between the exists() check and open (delete race, broken symlink), or reading it fails due to permissions or IO problems.

Common situations: Config file managed by a symlink into a ConfigMap/secret that was rotated; permission changes after a container restart; TOCTOU races in deployment scripts.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at sdks/java/expansion-service/src/main/java/org/apache/beam/sdk/expansion/service/ExpansionServiceOptions.java:124

      return AllowList.nothing();
    }
  }

  /** Loads the ExpansionService config. */
  class ExpansionServiceConfigFactory implements DefaultValueFactory<ExpansionServiceConfig> {

    @Override
    public ExpansionServiceConfig create(PipelineOptions options) {
      String configFile = options.as(ExpansionServiceOptions.class).getExpansionServiceConfigFile();
      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 ExpansionServiceConfig.parseFromYamlStream(stream);
        } catch (FileNotFoundException e) {
          throw new RuntimeException(
              "Could not parse the provided Expansion Service config file" + configFile, e);
        } catch (IOException e) {
          throw new RuntimeException(
              "Could not parse the provided Expansion Service config file" + configFile, e);
        }
      }

      // By default produces null.
      return ExpansionServiceConfig.empty();
    }
  }
}

View on GitHub (pinned to 12126d8942)