Failed to perform initial catalog synchronization

Error message

Failed to perform initial catalog synchronization

What it means

CatalogUpdateReceiver.start() catches any Throwable from the initial resync() and logs a warning rather than failing lifecycle start. The receiver starts anyway; the cache may be empty or incomplete until a later resync succeeds. Queries against the catalog may see missing tables until synchronization succeeds.

Solutions

Check the accompanying exception in the log for the root cause (connection refused, 404, auth) and fix connectivity/config to the catalog source.
Verify catalog sync configuration (coordinator host, port, auth credentials).
Ensure startup ordering so the catalog source is available before the receiver starts, or rely on later periodic resync.
Restart or wait for the next resync cycle and confirm catalogs appear in the cache.

Example fix

// before
// druid.catalog.sync.destination = wrong-host:8080
// after
// druid.catalog.sync.destination = coordinator-host:8080  (reachable catalog source)

Defensive patterns

Strategy: retry

Validate before calling

// verify reachability before lifecycle start
curl -f http://coordinator-host:8081/druid/coordinator/v1/isLeader

Try / catch

// catch-and-resync pattern
try { receiver.start(); } catch (Throwable t) {
  LOG.warn(t, "start failed; will retry resync");
  scheduler.schedule(receiver::resync, 30, SECONDS);
}

Prevention

Verify catalog sync endpoint config before deployment.
Sequence startup so the catalog source is healthy first.
Monitor initial-resync failures in logs/metrics and alert.

When it happens

Trigger: resync() throws at service startup because the catalog source (coordinator/HTTP endpoint) is unreachable, returns an error, or the fetched metadata fails to deserialize; lifecycle start (e.g. from testLifecycle) with a misconfigured catalog sync endpoint.

Common situations: Coordinator not yet up when broker starts (startup ordering); wrong host/port for the catalog sync config; network/authorization problems at boot; transient network blips during rolling restarts.

Related errors

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

Appendix: source

Thrown at extensions-core/druid-catalog/src/main/java/org/apache/druid/catalog/sync/CatalogUpdateReceiver.java:104

            }
            catch (Throwable t) {
              LOG.makeAlert(t, "Error occurred while refreshing catalog.").emit();
            }
          }
      );

      lifecycleLock.started();
      LOG.info("Catalog update receiver started");
    }
    finally {
      lifecycleLock.exitStart();
    }

    try {
      resync();
    }
    catch (Throwable t) {
      LOG.warn(t, "Failed to perform initial catalog synchronization");
    }
  }

  @LifecycleStop
  public void stop()
  {
    if (!lifecycleLock.canStop()) {
      throw new ISE("can't stop.");
    }

    LOG.info("Catalog update receiver stopped");
    exec.shutdownNow();
    lifecycleLock.exitStop();
  }

  private void resync() throws Exception
  {
    RetryUtils.retry(

View on GitHub (pinned to 9b90983fd2)