apache/druid · error · IAE

Invalid value of %s.maxThreads[%d]

Error message

Invalid value of %s.maxThreads[%d]

What it means

PeonMemoryManagementModule.getNumThreads validates druid.task.memory-management.maxThreads: only UNLIMITED (-1) or a positive integer is allowed; any other value (e.g. 0 or negative) throws IllegalArgumentException "Invalid value of %s.maxThreads[%d]" while creating the memory introspector at peon startup.

Source

Thrown at multi-stage-query/src/main/java/org/apache/druid/msq/guice/PeonMemoryManagementModule.java:107

  )
  {
    return new PeonProcessingBuffersProvider(
        processingPool,
        memoryIntrospector.numProcessingThreads()
    );
  }

  public static int getNumThreads(
      final TaskMemoryManagementConfig taskMemoryManagementConfig,
      final DruidProcessingConfig processingConfig
  )
  {
    if (taskMemoryManagementConfig.getMaxThreads() == TaskMemoryManagementConfig.UNLIMITED) {
      return processingConfig.getNumThreads();
    } else if (taskMemoryManagementConfig.getMaxThreads() > 0) {
      return Math.min(taskMemoryManagementConfig.getMaxThreads(), processingConfig.getNumThreads());
    } else {
      throw new IAE(
          "Invalid value of %s.maxThreads[%d]",
          TaskMemoryManagementConfig.BASE_PROPERTY,
          taskMemoryManagementConfig.getMaxThreads()
      );
    }
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Set druid.task.memory-management.maxThreads to a positive integer
2. Remove the property entirely or set it to -1 (TaskMemoryManagementConfig.UNLIMITED) to follow druid.processing.numThreads
3. Fix config-generation scripts to emit -1 instead of 0 for unlimited

Example fix

// before (runtime.properties)
druid.task.memory-management.maxThreads=0
// after
druid.task.memory-management.maxThreads=-1

int v = taskMemoryManagementConfig.getMaxThreads();
if (v != TaskMemoryManagementConfig.UNLIMITED && v <= 0) {
  throw new IllegalArgumentException("druid.task.memory-management.maxThreads must be positive or -1");
}

When it happens

Trigger: druid.task.memory-management.maxThreads set to 0 or a negative number other than the UNLIMITED sentinel in runtime.properties or task context; typo in sentinel value after config refactor.

Common situations: Copy-pasting example configs that use 0 for 'unlimited' (Druid uses -1/UNLIMITED); provisioning scripts generating maxThreads from an empty or invalid variable; mixing versions where the sentinel semantics differ.

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

• NotEnoughMemoryFault
• No such shuffleKind[%s]
• maxRetainedPartitionSketchBytes must be positive
• maxConcurrentStagesPerWorker must be >= 2 when pipelining
• maxConcurrentStagesPerWorker must be positive

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