apache/druid · error · IllegalStateException

Unhandled locator type:

Error message

Unhandled locator type: 

What it means

MemcachedCustomConnectionFactoryBuilder.createLocator maps a configured locator type onto a spymemcached locator/failure mode. When the configured value matches no known branch, the switch's default throws IllegalStateException listing the offending value, because there is no safe default mapping.

Solutions

1. Use one of the supported locator values accepted by MemcachedCache
2. Log and inspect the exact value in the exception message and correct the spelling
3. Check the Druid memcached extension docs for the accepted locator set

Example fix

// before
druid.cache.locator=ketamaHash
// after
druid.cache.locator=consistentHash

if (!SUPPORTED_LOCATORS.contains(config.getLocator())) {
  throw new IllegalArgumentException("Unsupported memcached locator: " + config.getLocator());
}

try {
  cache = MemcachedCache.create(cacheConfig);
} catch (IllegalStateException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unhandled locator type")) {
    throw new IllegalArgumentException("Fix the druid.cache locator value", e);
  }
  throw e;
}

When it happens

Trigger: Configuring a memcached locator value that is not one of the supported locator names while the cache connection factory is being built.

Common situations: Typo in the locator property, copying a locator name from a different memcached client library, upgrading spymemcached where a legacy locator name was removed.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Invalid value provided for `druid.cache.clientMode`. Value…
• Exception pulling item from cache
• Expected 0 resource count, got
• Unable to queue cache operation
• At least one of baseDir or files should be specified

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

Appendix: source

Thrown at server/src/main/java/org/apache/druid/client/cache/MemcachedCustomConnectionFactoryBuilder.java:83

      {
        switch (locator) {
          case ARRAY_MOD:
            return new ArrayModNodeLocator(nodes, getHashAlg());
          case CONSISTENT:
            return new KetamaNodeLocator(
                nodes,
                getHashAlg(),
                new DefaultKetamaNodeLocatorConfiguration()
                {
                  @Override
                  public int getNodeRepetitions()
                  {
                    return repetitions;
                  }
                }
            );
          default:
            throw new IllegalStateException("Unhandled locator type: " + locator);
        }
      }

      @Override
      public BlockingQueue<Operation> createOperationQueue()
      {
        return opQueueFactory == null ? super.createOperationQueue() : opQueueFactory.create();
      }

      @Override
      public BlockingQueue<Operation> createReadOperationQueue()
      {
        return readQueueFactory == null ? super.createReadOperationQueue() : readQueueFactory.create();
      }

      @Override
      public BlockingQueue<Operation> createWriteOperationQueue()
      {

View on GitHub (pinned to 9b90983fd2)