mem0ai/mem0 · error · APIError

Failed to ping server: ${error.message || "Unknown error"}

Error message

Failed to ping server: ${error.message || "Unknown error"}

What it means

This APIError is the catch-all wrapper around non-structured failures during the initialization ping to /v1/ping/: DNS failures, connection refused, TLS errors, timeouts, or fetch exceptions. Structured MemoryError/APIError cases are re-thrown unchanged; everything else is wrapped as 'Failed to ping server: <original message>' so the root cause text is preserved inside the message.

Source

Thrown at mem0-ts/src/client/mem0.ts:309

      if (!response || typeof response !== "object") {
        throw new APIError("Invalid response format from ping endpoint");
      }

      if (response.status !== "ok") {
        throw new APIError(response.message || "API Key is invalid");
      }

      const { orgId, projectId, userEmail } = response;

      if (orgId) this.organizationId = orgId;
      if (projectId) this.projectId = projectId;
      if (userEmail) this.telemetryId = userEmail;
    } catch (error: any) {
      // Pass through structured exceptions and APIError
      if (error instanceof MemoryError || error instanceof APIError) {
        throw error;
      } else {
        throw new APIError(
          `Failed to ping server: ${error.message || "Unknown error"}`,
        );
      }
    }
  }

  async add(
    messages: Array<Message>,
    options: AddMemoryOptions & Record<string, any> = {},
  ): Promise<Array<Memory>> {
    // Tightly scoped validation guard to resolve #5465
    if (!messages || (Array.isArray(messages) && messages.length === 0)) {
      throw new Error("Cannot process an empty messages payload.");
    }

    const payload = this._preparePayload(messages, options);
    const payloadKeys = Object.keys(payload);
    this._captureEvent("add", [payloadKeys]);

View on GitHub (pinned to 001c235229)

Solutions

1. Read the suffixed original message — 'ENOTFOUND' means DNS/host typo, 'ECONNREFUSED' means the self-hosted server is down, certificate errors point at TLS/proxy issues.
2. Verify connectivity: curl -v ${host}/v1/ping/ from the same environment/container.
3. Start or health-check your self-hosted Mem0 server before constructing clients.
4. Open egress to the API host in container/serverless network policies.

Example fix

# before: self-hosted server not running
MEM0_HOST=http://localhost:8080

# after: start it first
docker compose -f server/docker-compose.yaml up -d
# then run the app

async function canReachPing(host: string, timeoutMs = 5000): Promise<boolean> {
  try {
    const c = new AbortController();
    setTimeout(() => c.abort(), timeoutMs).unref?.();
    const r = await fetch(`${host}/v1/ping/`, { signal: c.signal });
    return r.ok;
  } catch {
    return false;
  }
}

if (!(await canReachPing(host))) throw new Error(`Cannot reach ${host}/v1/ping/ — check network/DNS/server`);

const isPingTransportError = (e: unknown): boolean =>
  e instanceof Error && e.message.startsWith('Failed to ping server');

try {
  const client = new MemoryClient({ apiKey, host });
  await client.users();
} catch (e) {
  if (isPingTransportError(e)) {
    await sleep(1000 * attempt++);
    return retryInit(); // transient network failures are safe to retry
  }
  throw e;
}

When it happens

Trigger: host unreachable (DNS typo, firewall, service down), TLS certificate failure on a self-hosted endpoint, network timeout from sandboxed serverless runtimes, or an offline dev machine — any transport-level error during client init.

Common situations: Self-hosted server not started yet; egress-blocked containers; typo'd hostnames (api.mem0.ai vs api.mem0.ai.); corporate MITM proxies breaking TLS to the API.

Related errors

• Invalid response format from ping endpoint
• HTTP ${resp.status}: ${detail}
• API Key is invalid
• Error getting embedding from AWS Bedrock model ${this.model}
• HuggingFace embedder requires an inference endpoint. Set `hu

AI-assisted analysis of mem0ai/mem0@001c235229 (2026-08-15). Data as JSON: /api/errors/95e4414be71673cf. Report an issue: GitHub.