ENSApi: DI init crashes instead of waiting when ENSIndexer metadata isn't published yet

[shrugs]

Summary

ENSApi crashes permanently (process.exit(1)) at startup if it initializes before ENSIndexer has published its ensnode.metadata, instead of waiting/retrying. This is a startup-ordering race: any deployment where ENSApi can come up before the indexer's first metadata write (fresh DB, co-located stacks, restarts) hard-fails the API.

Symptom

ERROR: Error initializing DI container
  DI container initialization failed: could not connect to ENS Root Chain RPC
  due to relation "ensnode.metadata" does not exist
 ELIFECYCLE  Command failed with exit code 1.

ENSApi exits and does not recover on its own; only a restart after the indexer has written metadata succeeds.

Root cause

• apps/ensapi/src/index.ts runs di.init().catch(() => process.exit(1)) — no retry.
• di.init() (apps/ensapi/src/di.ts) eagerly reads the indexer's published ensnode.metadata via stackInfoCache.read() / indexingStatusCache.read() and the root-chain RPC config derived from it. When ensnode.metadata doesn't exist yet, these throw and init rejects.

So a transient, expected startup-ordering condition (indexer hasn't published metadata yet) is treated as a fatal error.

Proposed fix

Treat "indexer metadata not published yet" as a retryable condition during DI init:

• Add a classifier isIndexerMetadataNotReadyError(err) matching the missing-relation / empty-metadata case.
• In di.init(), wrap the metadata-dependent initialization (the three cache reads + root-chain RPC config/getBlockNumber) in a bounded retry-with-backoff loop. On a "not ready" error: log and retry with backoff; on any other error: fail fast; give up after a configurable timeout (env, default ~10 min) so a genuine misconfig still surfaces. Ensure caches re-query on retry rather than caching the failure.

This makes ENSApi tolerant of being started before/alongside the indexer, which is the common case for fresh deployments and co-located dev/checkpoint stacks.

Notes

• Keep genuine config/connectivity failures fail-fast — only the metadata-not-ready class should retry.
• Found while running co-located indexer+ENSApi checkpoint stacks, where ENSApi reliably loses the race against the indexer's first metadata write and dies.

Part of #1360 (tracking).

[coderabbitai]

🔗 Related PRs

#1729 - ENSApi Integration Tests in CI [merged]
#2012 - Add "Startup sequence" sub-page to ENSIndexer docs [merged]
#2021 - Integrate ENSDb health check and readiness check into ENSApi probe endpoints [merged]
#2108 - hotfix: promote Queued chains past omnichain cursor on crash recovery [merged]
#2175 - fix(ensindexer): make bridged-resolver subregistry write order-independent [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[tk-o]

Nice catch, @shrugs. I was meant to work on this one as part of #2029 (still have some other work to be done there), but I like the proposed fix here 👍 Indeed, we need be able to wait for the ENSNode Metadata record to be created in DB. This should be a retryable error for certain short time (less than a minute).