apache/druid · error · IAE

Only %s protocols are allowed

Error message

Only %s protocols are allowed

What it means

HdfsInputSource restricts path schemes to an allowlist (allAllowedProtocols from HdfsInputSourceConfig, defaulting to a fixed set such as hdfs/file). throwIfInvalidProtocol rejects any path whose scheme is not in that list with this IllegalArgumentException listing the allowed protocols.

Source

Thrown at extensions-core/hdfs-storage/src/main/java/org/apache/druid/inputsource/hdfs/HdfsInputSource.java:143

      throw new IAE("'%s' must be a string or an array of strings", propertyName);
    }
  }

  public static void verifyProtocol(Configuration conf, HdfsInputSourceConfig config, String pathString)
  {
    Path path = new Path(pathString);
    try {
      throwIfInvalidProtocol(config, path.getFileSystem(conf).getScheme());
    }
    catch (IOException e) {
      throw new RuntimeException(e);
    }
  }

  private static void throwIfInvalidProtocol(HdfsInputSourceConfig config, String scheme)
  {
    if (!config.getAllowedProtocols().contains(StringUtils.toLowerCase(scheme))) {
      throw new IAE("Only %s protocols are allowed", config.getAllowedProtocols());
    }
  }

  /**
   * Matches Hadoop's FileInputFormat hidden-file filter: rejects paths whose name starts with '_' or '.'.
   */
  private static boolean isHiddenPath(Path path)
  {
    final String name = path.getName();
    return name.startsWith("_") || name.startsWith(".");
  }

  public static Collection<Path> getPaths(List<String> inputPaths, Configuration configuration) throws IOException
  {
    if (inputPaths.isEmpty()) {
      return Collections.emptySet();
    }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Use a scheme-appropriate path (hdfs://...) or switch to the dedicated s3/gs/azure input source for cloud storage.
2. Add the needed scheme to config: druid.inputsource.hdfs.allowedProtocols=["hdfs","file","s3a"] (comma-separated runtime property).
3. Check the exact allowed list in the error message and align your paths with it.
4. If protocols were intentionally restricted, request a config change from the cluster operator rather than bypassing it.

Example fix

// before
"paths": ["s3a://bucket/data"]   // hdfs input source
// after
"inputSource": {"type": "s3", "uris": ["s3://bucket/data"]}
// or on the hdfs source:
// druid.inputsource.hdfs.allowedProtocols=hdfs,file,s3a

static boolean protocolAllowed(String path, Set<String> allowed) {
  String scheme = path.contains("://") ? path.substring(0, path.indexOf("://")) : "";
  return allowed.contains(scheme.toLowerCase(Locale.ROOT));
}

try { verifyProtocol(conf, config, pathString); }
catch (IAE e) { log.error("Path scheme rejected; allowed: %s", config.getAllowedProtocols()); }

When it happens

Trigger: Ingesting via hdfs inputSource with a path using s3a://, gs://, http://, or another scheme not present in druid.inputsource.hdfs.allowedProtocols; also triggered when config explicitly narrows the allowlist and existing paths no longer qualify.

Common situations: Copying specs between clusters where one allows s3a and the other does not; security hardening that trimmed allowedProtocols; users mistakenly using the hdfs source for cloud object stores instead of the s3/gcs input sources.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• '%s' must be a string or an array of strings
• Failed to authenticate user principal [%s] with keytab [%s]
• This inputSource does not support input source based securit
• Skipping deep storage directory kill: relative path must not
• Couldn't deserialize authenticator userMap!

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/b6f06bff081f511c. Report an issue: GitHub.