apache/druid · error · IllegalArgumentException

Argument [%s] is not a valid URI

Error message

Argument [%s] is not a valid URI

What it means

CatalogUtils.stringListToUriList converts each string in a list to a java.net.URI and wraps any URISyntaxException into this IllegalArgumentException. It indicates one of the supplied URI strings cannot be parsed by the strict java.net.URI syntax rules (RFC 2396).

Source

Thrown at server/src/main/java/org/apache/druid/catalog/model/CatalogUtils.java:244

  {
    return stringListToUriList(stringToList(uris));
  }

  /**
   * Convert a list of strings to a list of {@link URI} objects.
   */
  public static List<URI> stringListToUriList(List<String> list)
  {
    if (list == null) {
      return null;
    }
    List<URI> uris = new ArrayList<>();
    for (String strValue : list) {
      try {
        uris.add(new URI(strValue));
      }
      catch (URISyntaxException e) {
        throw new IAE(StringUtils.format("Argument [%s] is not a valid URI", strValue));
      }
    }
    return uris;
  }

  /**
   * Merge the properties for an object using a set of updates in a map. If the
   * update value is {@code null}, then remove the property in the revised set. If the
   * property is known, use the column definition to merge the values. Else, the
   * update replaces any existing value.
   * <p>
   * This method does not validate the properties, except as needed to do a
   * merge. A separate validation step is done on the final, merged object.
   */
  public static Map<String, Object> mergeProperties(
      final Map<String, PropertyDefn<?>> properties,
      final Map<String, Object> source,
      final Map<String, Object> update

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Fix the offending string to be a valid URI; use file:/// scheme with forward slashes for local paths.
2. Percent-encode illegal characters (spaces as %20) or encode with new URI(null, rawString, null) before parsing.
3. Identify the bad element from the message (it prints the exact string) and validate all entries with a quick URI parse beforehand.

Example fix

// before
list.add("C:\\data\\lookups\\country.json");
// after
list.add("file:///C:/data/lookups/country.json");

for (String u : uriStrings) {
  try { new URI(u); } catch (URISyntaxException e) {
    throw new IllegalArgumentException("Not a valid URI: " + u);
  }
}

boolean isValidUri(String s) { try { new URI(s); return true; } catch (URISyntaxException e) { return false; } }

try { List<URI> uris = CatalogUtils.stringToUriList(raw); ... } catch (IllegalArgumentException e) { // e.getMessage() names the exact bad string; fix or skip it }

When it happens

Trigger: Calling stringToUriList or stringListToUriList with any element containing characters illegal in URIs, e.g. unescaped spaces, "|", "[", "]", or a malformed scheme like "C:\\path" on Windows.

Common situations: Windows file paths pasted as URIs ("C:\data\file.json" instead of "file:///C:/data/file.json"); spaces in lookup URIs that are not percent-encoded; angle-bracketed or quoted URIs copied from docs.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Don't know how to load SCHEME [%s] for URI [%s]
• One or more values are required for parameter %s
• Value [%s] is not valid for property [%s]
• Unable to parse line.
• Multiple lines present; unable to parse more than one per re

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