apache/druid · error · org.apache.druid.java.util.common.IAE

Unable to create storage connector [%s] for base path [%s]

Error message

Unable to create storage connector [%s] for base path [%s]

What it means

LocalFileStorageConnectorProvider.createStorageConnector catches the IOException thrown by the LocalFileStorageConnector constructor (it tries to create the base path directory on init) and rethrows it as an IllegalArgumentException. The provider cannot hand back a working connector when the base directory cannot be created.

Source

Thrown at processing/src/main/java/org/apache/druid/storage/local/LocalFileStorageConnectorProvider.java:54

  public static final String TYPE_NAME = "local";

  @JsonProperty
  final File basePath;

  @JsonCreator
  public LocalFileStorageConnectorProvider(@JsonProperty(value = "basePath", required = true) File basePath)
  {
    this.basePath = basePath;
  }

  @Override
  public StorageConnector createStorageConnector(File defaultTempDir)
  {
    try {
      return new LocalFileStorageConnector(basePath);
    }
    catch (IOException e) {
      throw new IAE(
          e,
          "Unable to create storage connector [%s] for base path [%s]",
          LocalFileStorageConnector.class.getSimpleName(),
          basePath
      );
    }
  }

  @Override
  public boolean equals(Object o)
  {
    if (this == o) {
      return true;
    }
    if (o == null || getClass() != o.getClass()) {
      return false;
    }
    LocalFileStorageConnectorProvider that = (LocalFileStorageConnectorProvider) o;

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Check the configured basePath and ensure the Druid user can create it (mkdir/chown)
2. Remove or rename any regular file sitting at the basePath
3. Mount the expected volume before Druid starts; verify in container entrypoint

Example fix

// before (druid config)
druid.storage.basePath=/root/var/druid
// after
druid.storage.basePath=/var/druid  # owned by the druid service user

File base = new File(basePath);
if (!base.exists() && !base.mkdirs()) {
  throw new IllegalStateException("cannot create base path " + basePath);
}
if (!base.isDirectory() || !base.canWrite()) {
  throw new IllegalStateException("base path not writable: " + basePath);
}

try { provider.get(); } catch (IllegalArgumentException e) { // check base path perms/exists, inspect cause IOException }

When it happens

Trigger: Requesting a storage connector via StorageConnectorProvider/get when basePath is invalid — e.g. path is not creatable because a parent does not exist and is not creatable, a file already occupies the path, or the process lacks write permission on the parent directory.

Common situations: Misconfigured druid.storage.basePath (typo, root-owned path); running Druid in a read-only container filesystem; a regular file already exists where the base directory is expected; segment/log dir mount not mounted at startup.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• taskLogDir [%s] must be a directory.
• Root extensions directory [%s] is not a directory!?
• The gRPC query server requires either a Basic or Anonymous a
• Metric [%s] not whitelisted.
• Can't load TrustStore. Truststore path or password is not se

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