apache/druid · error · IllegalArgumentException

Backfill tasks require 'useConcurrentLocks' to be set to…

Error message

Backfill tasks require 'useConcurrentLocks' to be set to true in the supervisor context to allow concurrent writes with the main supervisor tasks

What it means

SupervisorManager requires the supervisor context to enable concurrent locks before starting backfill tasks alongside the main supervisor tasks. Without useConcurrentLocks=true, backfill tasks would contend with main tasks for segment locks and the manager rejects the request with this message. The validation is part of validateResetAndBackfill and fires before any reset is performed.

Solutions

  1. Add "useConcurrentLocks": true to the supervisor's context (suspend, POST updated spec, resume), then retry
  2. If concurrent locks cannot be enabled, stop the supervisor and run backfill as a standalone batch ingestion task instead
  3. Verify with GET /druid/indexer/v1/supervisor/<id> that the context field shows the updated flag

Example fix

// before
{"context": {"maxActiveTaskGroups": 3}}
// after
{"context": {"maxActiveTaskGroups": 3, "useConcurrentLocks": true}}
// then retry POST /druid/indexer/v1/supervisor/<id>/reset
Defensive patterns

Strategy: validation

Validate before calling

const spec = await (await fetch(`${overlord}/druid/indexer/v1/supervisor/${id}`)).json();
if (!spec.spec.context || spec.spec.context.useConcurrentLocks !== true) throw new Error('enable useConcurrentLocks before backfill');

Type guard

function hasConcurrentLocks(spec) { return spec?.spec?.context?.useConcurrentLocks === true; }

Try / catch

try { await resetBackfill(id); } catch (e) { if (/useConcurrentLocks/.test(e.message)) { await enableConcurrentLocks(id); await resetBackfill(id); } else throw e; }

Prevention

When it happens

Trigger: resetToLatestAndBackfill (POST /druid/indexer/v1/supervisor/<id>/reset with backfill) where specHasConcurrentLocks(streamSpec) is false — i.e. the supervisor context lacks useConcurrentLocks=true.

Common situations: Pre-existing supervisors created before concurrent locks were introduced, whose context never set the flag; spec copied from an old template; operator enabling backfill without reviewing the locking requirements.

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

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

Appendix: source

Thrown at indexing-service/src/main/java/org/apache/druid/indexing/overlord/supervisor/SupervisorManager.java:516

    return ImmutableMap.of(
        "id", id,
        "backfillSupervisorId", backfillSupervisorId
    );
  }

  private void validateResetAndBackfill(
      String id,
      SeekableStreamSupervisor streamSupervisor,
      SeekableStreamSupervisorSpec streamSpec
  )
  {
    if (streamSupervisor.getIoConfig().isUseEarliestSequenceNumber()) {
      throw new IAE("Reset with skipped offsets is not supported when useEarliestOffset is true.");
    }

    if (!specHasConcurrentLocks(streamSpec)) {
      throw new IAE(
          "Backfill tasks require 'useConcurrentLocks' to be set to true in the supervisor context to allow concurrent writes with the main supervisor tasks"
      );
    }

    if (streamSupervisor.getState() != SupervisorStateManager.BasicState.RUNNING) {
      throw new IAE("Supervisor[%s] must be in a RUNNING state to perform a reset and backfill", id);
    }
  }

  public boolean checkPointDataSourceMetadata(
      String supervisorId,
      int taskGroupId,
      DataSourceMetadata previousDataSourceMetadata
  )
  {
    try {
      Preconditions.checkState(started, "SupervisorManager not started");
      Preconditions.checkNotNull(supervisorId, "supervisorId cannot be null");

View on GitHub (pinned to 9b90983fd2)