hcengineering/platform · error · Error

Max retries (${maxRetries}) exceeded while loading chunks fo

Error message

Max retries (${maxRetries}) exceeded while loading chunks for domain ${domain}

What it means

loadChangesFromServer retries fetching backup chunks for a domain up to maxRetries times; when retryCount still exceeds the limit it logs 'Max retries exceeded' and throws this Error. It signals persistent failure to retrieve change chunks from the server during backup/traversal.

Source

Thrown at server/backup/src/backup.ts:466

              workspace: workspaceId,
              url: wsIds.url
            })
            await ctx.with('closeChunk', {}, async () => {
              await connection.closeChunk(ctx, idx as number)
            })
            break
          }
        } catch (err: any) {
          retryCount++
          ctx.error('failed to load chunks', { error: err, retryCount, maxRetries })
          if (idx !== undefined) {
            await ctx.with('closeChunk', {}, async () => {
              await connection.closeChunk(ctx, idx as number)
            })
          }
          if (retryCount >= maxRetries) {
            ctx.error('Max retries exceeded in loadChangesFromServer', { domain, retryCount })
            throw new Error(`Max retries (${maxRetries}) exceeded while loading chunks for domain ${domain}`)
          }
          // Try again with delay
          await new Promise<void>((resolve) => setTimeout(resolve, 1000 * retryCount))
          idx = undefined
          processed = 0
        }
      }
      return { changed, needRetrieveChunks }
    }

    let domainChanges = 0
    async function processDomain (
      ctx: MeasureContext,
      domain: Domain,
      progress: (value: number) => Promise<void>
    ): Promise<void> {
      const changes: Snapshot = {
        added: new Map(),

View on GitHub (pinned to 63e28dc964)

Solutions

Verify connectivity to the backup/transactor server and retry the backup operation.
Increase maxRetries (and note the built-in backoff is 1000ms * retryCount) for unstable networks.
Check server logs for the underlying chunk-load failure causing each retry.
Re-run the backup during lower load or from a node closer to the server.

Example fix

// config
// before
const maxRetries = 3
// after
const maxRetries = 10 // tolerate longer transient outages

Defensive patterns

Strategy: retry

Validate before calling

// pre-check server reachability before the backup
const ok = await fetch(`${serverUrl}/health`).then(r => r.ok).catch(() => false)
if (!ok) throw new Error('Backup server unreachable; aborting before chunk loading')

Try / catch

try {
  await loadChangesFromServer(ctx, ...)
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Max retries')) {
    // exponential backoff, then reschedule the whole backup job
  } else throw err
}

Prevention

Run backups on stable network paths and monitor server health.
Tune maxRetries relative to network reliability; the built-in backoff is linear (1s * attempt).
Alert on the ctx.error log line before the throw to catch degradation early.
Resume/incremental backup support reduces cost of a failed run.

When it happens

Trigger: Repeated chunk load failures (network errors, server 5xx, timeouts) during loadChangesFromServer such that retryCount >= maxRetries while iterating chunks for a domain; callers include changed/needRetrieveChunks.

Common situations: Backup worker running against a flaky or overloaded transactor; long-running backups interrupted by network partitions; server restarted mid-backup; maxRetries configured too low for an unstable network.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/9f8eb9c503cf1eef. Report an issue: GitHub.