What causes "Worker is still initializing, please retry" in thedotmack/claude-mem?

Poll /api/readiness until it returns 200 before sending traffic

Worker is still initializing, please retry

Error message

Worker is still initializing, please retry

What it means

GET /api/readiness returns 503 with status 'initializing' until options.getInitializationComplete() flips true — the worker finishes database setup and boot-time caching before declaring ready. This is a designed transient signal, not a crash; readiness flips to 200 once initialization completes.

Source

Thrown at src/services/server/Server.ts:251

        platform: process.platform,
        pid: process.pid,
        initialized: this.options.getInitializationComplete(),
        mcpReady: this.options.getMcpReady(),
        ai: this.options.getAiStatus(),
        dependencies: dependencyHealth,
        rateLimits: globalRateLimitStore.getMostRecentByWindow(),
        ...(queueHealth ? { queue: queueHealth } : {}),
      });
    });

    this.app.get('/api/readiness', (_req: Request, res: Response) => {
      if (this.options.getInitializationComplete()) {
        res.status(200).json({
          status: 'ready',
          mcpReady: this.options.getMcpReady(),
        });
      } else {
        res.status(503).json({
          status: 'initializing',
          message: 'Worker is still initializing, please retry',
        });
      }
    });

    this.app.get('/api/version', (_req: Request, res: Response) => {
      res.status(200).json({ version: BUILT_IN_VERSION });
    });

    this.app.get('/api/instructions', (req: Request, res: Response) => {
      const topic = (req.query.topic as string) || 'all';
      const operation = req.query.operation as string | undefined;

      if (topic && !ALLOWED_TOPICS.includes(topic)) {
        return res.status(400).json({ error: 'Invalid topic' });
      }

View on GitHub (pinned to e2d1df569a)

Solutions

Poll /api/readiness until it returns 200 before sending traffic
Raise probe initialDelaySeconds / failureThreshold in Kubernetes or compose healthchecks
Gate integration tests on the readiness endpoint rather than a fixed sleep

Example fix

// before
startServer(); await sleep(1000); runTests(); // may hit 503

// after
startServer();
await waitUntil(async () => (await fetch(`${base}/api/readiness`)).status === 200);
runTests();

Defensive patterns

Strategy: retry

Validate before calling

async function waitForReady(base: string, timeoutMs = 30_000): Promise<void> {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const res = await fetch(`${base}/api/readiness`);
    if (res.status === 200) return;
    const body = await res.json().catch(() => null);
    if (!body || body.status !== 'initializing') throw new Error(`readiness probe failed: ${res.status}`);
    await new Promise(r => setTimeout(r, 500)); // backoff between polls
  }
  throw new Error('server did not become ready in time');
}

Type guard

function isInitializing(status: number, body: unknown): body is { status: 'initializing'; message: string } {
  return status === 503 && typeof body === 'object' && body !== null && (body as { status?: string }).status === 'initializing';
}

Try / catch

let res = await fetch(`${base}/api/readiness`);
while (res.status === 503) {
  await new Promise(r => setTimeout(r, 500)); // transient by design: retry with backoff
  res = await fetch(`${base}/api/readiness`);
}
if (!res.ok) throw new Error(`server unhealthy: ${res.status}`);

Prevention

Gate all traffic on /api/readiness returning 200 instead of fixed sleeps
Set container probe initialDelaySeconds/failureThreshold to cover migrations
First-run and large databases init slower — size the retry budget accordingly

When it happens

Trigger: Probing /api/readiness (or racing real API calls) during startup, especially first run with migrations; large databases or slow disks lengthen the window.

Common situations: Container orchestrators probing with initialDelaySeconds too small; test suites starting the server and immediately running requests; startup scripts chaining server start + first request with no wait.

Related errors

AI-assisted analysis of thedotmack/claude-mem@e2d1df569a (2026-08-20). Data as JSON: /api/errors/3d00c01008255fee. Report an issue: GitHub.