apache/druid · error · IAE

Path must start with '/'

Error message

Path must start with '/'

What it means

TaskLocation.makeURL builds the URL used to fetch task logs, and requires the encoded path-and-query string to begin with '/'. A path missing the leading slash would otherwise produce a malformed relative URL, so an IAE is thrown.

Source

Thrown at processing/src/main/java/org/apache/druid/indexer/TaskLocation.java:140

      return HostAndPort.fromParts(host, thePort).toString();
    }
  }

  public URL makeURL(final String encodedPathAndQueryString) throws MalformedURLException
  {
    final String scheme;
    final int portToUse;

    if (tlsPort > 0) {
      scheme = "https";
      portToUse = tlsPort;
    } else {
      scheme = "http";
      portToUse = port;
    }

    if (!encodedPathAndQueryString.startsWith("/")) {
      throw new IAE("Path must start with '/'");
    }

    // Use URL constructor, not URI, since the path is already encoded.
    return new URL(scheme, host, portToUse, encodedPathAndQueryString);
  }

  @Override
  public String toString()
  {
    return "TaskLocation{" +
           "host='" + host + '\'' +
           ", port=" + port +
           ", tlsPort=" + tlsPort +
           ", k8sPodName=" + k8sPodName +
           '}';
  }

  @Override

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Ensure the path argument starts with '/' before calling makeURL/makeTaskLocationURL.
2. Normalize the path with a leading slash programmatically.
3. Check the source of the path (config or API) for missing slash formatting.

Example fix

// before
String path = "status/abc/log";
// after
String path = (p.startsWith("/") ? p : "/" + p);

String path = rawPath.startsWith("/") ? rawPath : "/" + rawPath;
taskLocation.makeTaskLocationURL(host, port, useTls, path);

boolean isValidLogPath(String p) { return p != null && p.startsWith("/"); }

try { url = location.makeTaskLocationURL(host, port, tls, path); } catch (IAE e) { if (e.getMessage().contains("Path must start")) { path = "/" + path; url = location.makeTaskLocationURL(host, port, tls, path); } }

When it happens

Trigger: Calling makeTaskLocationURL (or makeURL) with a log file path / pathAndQueryString that does not start with '/', e.g. 'status/123/log' instead of '/status/123/log'.

Common situations: Custom task log reporters or manually constructed TaskLocation with a hand-built path; overlord/task-status UI integrations that build log paths from non-standard sources.

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

• Unknown JDBC connection scheme: %s
• Path must start with '/'
• Aggregation [%s] does not support column [%s] of type [%s].
• Cannot accept both 'splitPoints' and 'numBins'
• at least 2 bins expected

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