apache/druid · error · IllegalArgumentException

Pod adapter [%s] requires the local Overlord pod namespace f

Error message

Pod adapter [%s] requires the local Overlord pod namespace for multik8s. Set either [druid.indexer.runner.overlordNamespace] or [druid.indexer.runner.namespace], or set [druid.indexer.runner.k8s.adapter.type=%s].

What it means

Thrown by getOverlordPodSourceNamespace in MultipleKubernetesTaskRunnerFactory when a pod-template-based adapter (PodTemplateTaskAdapter) is selected but the Overlord's own pod namespace cannot be determined from the multik8s cluster configuration. The pod template runs tasks in the Overlord's namespace, so Druid requires either an explicit overlordNamespace/namespace property or a cluster entry without a kubeconfigPath (local cluster) that defines a taskNamespace.

Source

Thrown at extensions-core/kubernetes-overlord-extensions/src/main/java/org/apache/druid/k8s/overlord/MultipleKubernetesTaskRunnerFactory.java:433

  {
    final String overlordNamespace = runnerConfig.getOverlordNamespace();
    if (overlordNamespace != null && !overlordNamespace.trim().isEmpty()) {
      return overlordNamespace;
    }

    final String namespace = runnerConfig.getNamespace();
    if (namespace != null && !namespace.trim().isEmpty()) {
      return namespace;
    }

    if (enabledClusters.size() == 1) {
      final MultipleKubernetesTaskRunnerConfig.KubernetesCluster cluster = enabledClusters.get(0);
      if (cluster.getKubeconfigPath() == null || cluster.getKubeconfigPath().trim().isEmpty()) {
        return cluster.getTaskNamespace();
      }
    }

    throw new IAE(
        "Pod adapter [%s] requires the local Overlord pod namespace for multik8s. Set either "
        + "[druid.indexer.runner.overlordNamespace] or [druid.indexer.runner.namespace], or set "
        + "[druid.indexer.runner.k8s.adapter.type=%s].",
        getAdapterType() == null ? SingleContainerTaskAdapter.TYPE : getAdapterType(),
        PodTemplateTaskAdapter.TYPE
    );
  }

  private KubernetesTaskRunnerStaticConfig getPerClusterConfiguration(
      MultipleKubernetesTaskRunnerConfig.KubernetesCluster cluster
  )
  {
    return new KubernetesTaskRunnerStaticConfig(
        cluster.getTaskNamespace(),
        cluster.getOverlordIdentifier(),
        this.runnerConfig.getK8sTaskPodNamePrefix(),
        this.runnerConfig.isDebugJobs(),
        this.runnerConfig.isSidecarSupport(),

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Set druid.indexer.runner.overlordNamespace (or druid.indexer.runner.namespace) to the namespace the Overlord pod runs in
2. If the Overlord runs inside one of the configured clusters, remove kubeconfigPath from that cluster entry so its taskNamespace is used
3. Alternatively switch to a different adapter via druid.indexer.runner.k8s.adapter.type=e.g. singleContainer or multiContainer, which does not require the local namespace

Example fix

// before
druid.indexer.runner.k8s.adapter.type=podTemplate
# no namespace configured

// after
druid.indexer.runner.k8s.adapter.type=podTemplate
druid.indexer.runner.overlordNamespace=druid

String adapter = props.getProperty("druid.indexer.runner.k8s.adapter.type");
String ns = props.getProperty("druid.indexer.runner.overlordNamespace",
            props.getProperty("druid.indexer.runner.namespace"));
if (("podTemplate".equals(adapter) || adapter == null) && ns == null) {
    throw new IllegalArgumentException(
        "podTemplate adapter needs druid.indexer.runner.overlordNamespace or druid.indexer.runner.namespace");
}

When it happens

Trigger: Configuring druid.indexer.runner.k8s.adapter.type=podTemplate (or the primary cluster uses a pod adapter) while: enabledClusters is empty, or the only enabled cluster has a non-empty kubeconfigPath (remote cluster, so its namespace is not the Overlord's local namespace) and neither druid.indexer.runner.overlordNamespace nor druid.indexer.runner.namespace is set.

Common situations: Multi-cluster (multik8s) setups where every cluster entry specifies a kubeconfigPath; fresh deployments that enabled the podTemplate adapter but never set the Overlord namespace property; operators assuming the cluster's taskNamespace doubles as the Overlord pod namespace.

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

• Invalid pod adapter [%s], only pod adapter [%s] can be speci
• Pod template task adapter requires a base pod template to be
• Pod template file not specified for [%s]
• Failed to create K8s ApiClient instance
• Invalid pod adapter [%s], only pod adapter [%s] can be speci

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