apache/druid · error · IllegalStateException

Cannot load resource

Error message

Cannot load resource: [%s]

What it means

StringUtils.getResource(Object ref, String resource) reads the classpath resource with IOUtils.toString; if reading throws an IOException (I/O error while reading, stream closed/broken), it wraps it in IllegalStateException "Cannot load resource: [%s]". This is distinct from the resource being absent (which gives "Resource not found").

Solutions

1. Verify the jar/classpath entry is intact (checksum, redeploy the artifact).
2. Rebuild and redeploy the application to replace a corrupted artifact.
3. Inspect the wrapped cause (e.getCause()) to identify the underlying IOException source.
4. Catch IllegalStateException around getResource and fall back to a copy of the resource bundled elsewhere.

Example fix

// before
String tpl = StringUtils.getResource(Main.class, "/templates/x.sql");
// after
String tpl;
try {
  tpl = StringUtils.getResource(Main.class, "/templates/x.sql");
} catch (IllegalStateException e) {
  LOG.error(e, "Failed to load resource; using default");
  tpl = DEFAULT_TEMPLATE;
}

try (InputStream is = ref.getClass().getResourceAsStream(resource)) { if (is != null) { is.readAllBytes(); } } catch (IOException e) { /* resource unreadable — handle before calling */ }

try {
  return StringUtils.getResource(ref, resource);
} catch (IllegalStateException e) {
  LOG.error(e.getCause(), "Cannot load resource %s", resource);
  throw e;
}

When it happens

Trigger: Calling StringUtils.getResource(ref, path) when the underlying stream fails mid-read — e.g. a corrupted jar, an I/O error on a filesystem-backed classpath entry, or a stream closed by another component.

Common situations: Damaged or partially-downloaded jars in deployment; container/classloader issues reading nested resources; disk errors on shared filesystems.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Resource not found: [ ]
• Cannot load JDBC driver class
• Could not find on the classpath. The MySQL Connector…
• Encountered error while reading the output of stage
• Expected [ ] found [ ]. Unknown class for context factory…

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/java/util/common/StringUtils.java:777

  {
    if (s == null || s.length() <= maxBytes) {
      return s;
    } else {
      return s.substring(0, maxBytes);
    }
  }

  public static String getResource(Object ref, String resource)
  {
    try {
      InputStream is = ref.getClass().getResourceAsStream(resource);
      if (is == null) {
        throw new ISE("Resource not found: [%s]", resource);
      }
      return IOUtils.toString(is, StandardCharsets.UTF_8);
    }
    catch (IOException e) {
      throw new ISE(e, "Cannot load resource: [%s]", resource);
    }
  }

  /**
   This method is removed from commons lang3.
   https://commons.apache.org/proper/commons-lang/article3_0.html
   */
  public static String escapeSql(String str)
  {
    return str == null ? null : StringUtils.replace(str, "'", "''");
  }

  /**
   * Uses {@link StringEscapeUtils#escapeHtml4} to escape the HTML entities in
   * the given string. This method can be used to sanitize a string for XSS.
   */
  public static String escapeHtml(String value)
  {

View on GitHub (pinned to 9b90983fd2)