apache/beam · error · java.lang.RuntimeException

Could not parse the provided allowlist file

Error message

Could not parse the provided allowlist file 

What it means

Wraps a FileNotFoundException thrown while opening the allowlist file for parsing in AllowList.create. Although existence was just checked, the open can still fail; the service rethrows as a RuntimeException labeled 'Could not parse the provided allowlist file' with the path and cause attached.

Solutions

1. Re-check that the file exists and is readable right before starting the service, then retry startup.
2. Resolve or remove broken symlinks in the path.
3. Fix filesystem permissions so the service user can read the file.
4. Inspect the wrapped cause (e) for the precise errno (e.g. No such file, Permission denied).

Example fix

// before
java -jar expansion-service.jar --allowListFile=/stale/symlink.yml
// after
ls -lL /stale/symlink.yml   # verify target exists, then point to the real file
java -jar expansion-service.jar --allowListFile=/real/allowlist.yml

File f = new File(allowListPath);
if (!f.isFile() || !f.canRead()) {
  throw new IllegalStateException("Allowlist not readable (check symlink/permissions): " + allowListPath);
}

try {
  startExpansionService(options);
} catch (RuntimeException e) {
  if (e.getCause() instanceof FileNotFoundException) { /* file vanished or broken symlink; re-verify and retry */ }
  throw e;
}

When it happens

Trigger: A race where the allowlist file is deleted between the exists() check and new FileInputStream(); a broken symlink or permission-denied scenario surfaced as FileNotFoundException on open.

Common situations: File removed by a cleanup job or container restart mid-startup; symlink pointing to a target that no longer exists; TOCTOU between validation and open in scripts that manage config files.

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

• Could not parse the provided Expansion Service config file
• Allow list file does not exist
• AUTO is applicable only to reading files
• AUTO is not supported for writing
• AvroRowWriter is not readable

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

Appendix: source

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

  class JavaClassLookupAllowListFactory implements DefaultValueFactory<AllowList> {

    @Override
    public AllowList create(PipelineOptions options) {
      String allowListFile =
          options.as(ExpansionServiceOptions.class).getJavaClassLookupAllowlistFile();
      if (allowListFile != null) {
        if (allowListFile.equals("*")) {
          return AllowList.everything();
        }
        File allowListFileObj = new File(allowListFile);
        if (!allowListFileObj.exists()) {
          throw new IllegalArgumentException(
              "Allow list file " + allowListFile + " does not exist");
        }
        try (InputStream stream = new FileInputStream(allowListFileObj)) {
          return AllowList.parseFromYamlStream(stream);
        } catch (FileNotFoundException e) {
          throw new RuntimeException(
              "Could not parse the provided allowlist file " + allowListFile, e);
        } catch (IOException e) {
          throw new RuntimeException(
              "Could not parse the provided allowlist file " + allowListFile, e);
        }
      }

      // By default produces an empty allow-list.
      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();

View on GitHub (pinned to 12126d8942)