apache/druid · error · IllegalArgumentException

Failed to load pod template file for

Error message

Failed to load pod template file for [%s] at [%s]

What it means

Thrown by DynamicConfigPodTemplateSelector.loadPodTemplate when reading or unmarshalling the configured pod template file fails for any reason — the file cannot be opened/read, or its YAML/JSON content is not a valid Kubernetes PodTemplate. The original exception is attached as the cause and the message names both the config property and file path so the operator can locate the bad input.

Solutions

1. Inspect the wrapped cause in the stack trace to distinguish file-open failure from parse failure
2. Verify the file exists at the configured path and is readable inside the Overlord container (mount the file into the pod if containerized)
3. Validate the template file is syntactically valid YAML/JSON and deserializes as a PodTemplate (kubectl apply --dry-run=client or a local unmarshal check)
4. Fix the path in druid.indexer.runner.k8s.podTemplate.<key> if the file was moved

Example fix

// before
druid.indexer.runner.k8s.podTemplate.base=/etc/druid/k8s/base-tempalte.yaml  # typo, file missing

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

String path = props.getProperty("druid.indexer.runner.k8s.podTemplate." + key);
File f = new File(path);
if (!f.isFile() || !f.canRead()) {
    throw new IllegalArgumentException("Pod template file unreadable: " + f.getAbsolutePath());
}
// Optionally dry-run parse:
try (InputStream in = Files.newInputStream(f.toPath())) {
    Serialization.unmarshal(in, PodTemplate.class);
} catch (Exception e) {
    throw new IllegalArgumentException("Invalid pod template YAML at " + path, e);
}

When it happens

Trigger: Files.newInputStream fails (missing file, permission denied, bad path) or Serialization.unmarshal to PodTemplate.class throws (invalid YAML/JSON syntax, wrong Kubernetes resource kind, unsupported fields) — any exception from the try block is wrapped into this IAE.

Common situations: Typo in the file path or file deleted after config was written; template copied from a Deployment/Pod spec rather than a valid PodTemplate shape; indentation/YAML syntax errors; the Overlord lacks filesystem read permission or the file is not mounted into the container.

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

• Pod template file not specified for
• Pod template task adapter requires a base pod template to…
• Task [ ] requested pod template [ ] via context key, but no…
• At least one task runner must be enabled
• can't start.

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

Appendix: source

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

  private PodTemplate loadPodTemplate(String key, Properties properties) throws IAE
  {
    String property = TASK_PROPERTY + key;
    String podTemplateFile = properties.getProperty(property);
    if (podTemplateFile == null) {
      throw new IAE("Pod template file not specified for [%s]", property);
    }

    try {
      // Use Optional to assert unmarshal result is non-null.
      Optional<PodTemplate> maybeTemplate = Optional.of(Serialization.unmarshal(
          Files.newInputStream(new File(podTemplateFile).toPath()),
          PodTemplate.class
      ));

      return maybeTemplate.get();
    }
    catch (Exception e) {
      throw new IAE(e, "Failed to load pod template file for [%s] at [%s]", property, podTemplateFile);
    }
  }

  @SuppressWarnings("ResultOfMethodCallIgnored")
  private void validateTemplateSupplier(Supplier<PodTemplate> templateSupplier) throws IAE
  {
    templateSupplier.get();
  }

  @Override
  public Optional<PodTemplateWithName> getPodTemplateForTask(Task task)
  {
    String requested = task.getContextValue(DruidK8sConstants.TASK_CONTEXT_POD_TEMPLATE_SELECTION_KEY);

    if (requested != null && effectiveConfig.isAllowTaskPodTemplateSelection()) {
      Supplier<PodTemplate> supplier = podTemplates.get(requested);
      if (supplier == null) {
        throw new IAE(

View on GitHub (pinned to 9b90983fd2)