apache/druid · error · IllegalArgumentException

Pod template task adapter requires a base pod template to be

Error message

Pod template task adapter requires a base pod template to be specified under druid.indexer.runner.k8s.podTemplate.base

What it means

Thrown by DynamicConfigPodTemplateSelector.initializeTemplatesFromFileSystem when the podTemplate task adapter is used with dynamic pod template selection but no 'base' pod template file is configured. The selector builds a map of pod templates from druid.indexer.runner.k8s.podTemplate.<key> properties and requires a mandatory 'base' key (druid.indexer.runner.k8s.podTemplate.base) from which other templates derive.

Source

Thrown at extensions-core/kubernetes-overlord-extensions/src/main/java/org/apache/druid/k8s/overlord/taskadapter/DynamicConfigPodTemplateSelector.java:69

  private final KubernetesTaskRunnerEffectiveConfig effectiveConfig;
  // Supplier allows Overlord to read the most recent pod template file without calling initializeTemplatesFromFileSystem() again.
  private HashMap<String, Supplier<PodTemplate>> podTemplates;

  public DynamicConfigPodTemplateSelector(
      Properties properties,
      KubernetesTaskRunnerEffectiveConfig effectiveConfig
  )
  {
    this.properties = properties;
    this.effectiveConfig = effectiveConfig;
    initializeTemplatesFromFileSystem();
  }

  private void initializeTemplatesFromFileSystem() throws IAE
  {
    Set<String> taskAdapterTemplateKeys = getTaskAdapterTemplatesKeys(properties);
    if (!taskAdapterTemplateKeys.contains("base")) {
      throw new IAE(
          "Pod template task adapter requires a base pod template to be specified under druid.indexer.runner.k8s.podTemplate.base");
    }

    HashMap<String, Supplier<PodTemplate>> podTemplateMap = new HashMap<>();
    for (String taskAdapterTemplateKey : taskAdapterTemplateKeys) {
      Supplier<PodTemplate> templateSupplier = () -> loadPodTemplate(taskAdapterTemplateKey, properties);
      validateTemplateSupplier(templateSupplier);
      podTemplateMap.put(taskAdapterTemplateKey, templateSupplier);
    }

    podTemplates = podTemplateMap;
  }

  private Set<String> getTaskAdapterTemplatesKeys(Properties properties)
  {
    Set<String> taskAdapterTemplates = new HashSet<>();

    for (String runtimeProperty : properties.stringPropertyNames()) {

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Add the base template property: druid.indexer.runner.k8s.podTemplate.base=/path/to/base-pod-template.yaml
2. Verify the property key is exactly podTemplate.base (lowercase, no typos)
3. Create a minimal valid base Pod YAML file if one does not yet exist

Example fix

// before
# only specific templates present
druid.indexer.runner.k8s.podTemplate.batch=/etc/druid/k8s/batch.yaml

// after
druid.indexer.runner.k8s.podTemplate.base=/etc/druid/k8s/base.yaml
druid.indexer.runner.k8s.podTemplate.batch=/etc/druid/k8s/batch.yaml

Properties props = ...;
boolean hasBase = props.stringPropertyNames().stream()
    .anyMatch(p -> p.startsWith("druid.indexer.runner.k8s.podTemplate."));
if (hasBase && props.getProperty("druid.indexer.runner.k8s.podTemplate.base") == null) {
    throw new IllegalArgumentException(
        "druid.indexer.runner.k8s.podTemplate.base is required when using podTemplate keys");
}

When it happens

Trigger: Initializing DynamicConfigPodTemplateSelector with a Properties object that contains podTemplate entries for task adapters but no podTemplate.base property; typically the operator added specific templates (e.g. podTemplate.batch) but skipped the required base.

Common situations: Migrating to the podTemplate adapter from singleContainer/multiContainer and only copying partial template config; renaming the base property key by mistake; documentation examples showing only non-base templates.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Pod template file not specified for [%s]
• Invalid pod adapter [%s], only pod adapter [%s] can be speci
• Pod adapter [%s] requires the local Overlord pod namespace f
• Task [%s] requested pod template [%s] via context key, but n
• Failed to create K8s ApiClient instance

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