{"record":{"id":"d66dd63465b5cdca","repo":"apache/druid","slug":"failed-to-perform-initial-catalog-synchronization","errorCode":null,"errorMessage":"Failed to perform initial catalog synchronization","messagePattern":"Failed to perform initial catalog synchronization","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"extensions-core/druid-catalog/src/main/java/org/apache/druid/catalog/sync/CatalogUpdateReceiver.java","lineNumber":104,"sourceCode":"            }\n            catch (Throwable t) {\n              LOG.makeAlert(t, \"Error occurred while refreshing catalog.\").emit();\n            }\n          }\n      );\n\n      lifecycleLock.started();\n      LOG.info(\"Catalog update receiver started\");\n    }\n    finally {\n      lifecycleLock.exitStart();\n    }\n\n    try {\n      resync();\n    }\n    catch (Throwable t) {\n      LOG.warn(t, \"Failed to perform initial catalog synchronization\");\n    }\n  }\n\n  @LifecycleStop\n  public void stop()\n  {\n    if (!lifecycleLock.canStop()) {\n      throw new ISE(\"can't stop.\");\n    }\n\n    LOG.info(\"Catalog update receiver stopped\");\n    exec.shutdownNow();\n    lifecycleLock.exitStop();\n  }\n\n  private void resync() throws Exception\n  {\n    RetryUtils.retry(","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/extensions-core/druid-catalog/src/main/java/org/apache/druid/catalog/sync/CatalogUpdateReceiver.java#L86-L122","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n// druid.catalog.sync.destination = wrong-host:8080\n// after\n// druid.catalog.sync.destination = coordinator-host:8080  (reachable catalog source)","handlingStrategy":"retry","validationCode":"// verify reachability before lifecycle start\ncurl -f http://coordinator-host:8081/druid/coordinator/v1/isLeader","typeGuard":null,"tryCatchPattern":"// catch-and-resync pattern\ntry { receiver.start(); } catch (Throwable t) {\n  LOG.warn(t, \"start failed; will retry resync\");\n  scheduler.schedule(receiver::resync, 30, SECONDS);\n}","preventionTips":["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."],"tags":["startup","resync","catalog-sync","connectivity"],"backgroundTag":"upstream-api-error","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}