bytedance/deer-flow · error

Agent '${name}' not found

Error message

Agent '${name}' not found

What it means

Raised by Mem0Config.resolve_api_key() when the environment variable named by api_key_env is unset or contains only whitespace. The mem0 backend deliberately reads its credential from the environment (default MEM0_API_KEY) instead of config.yaml so the key never lands in a file that could be committed.

Source

Thrown at frontend/src/core/agents/api.ts:48

    super(message);
    this.name = "AgentsApiDisabledError";
  }
}

function isAgentsApiDisabledDetail(detail: string | undefined): boolean {
  return typeof detail === "string" && detail.includes("agents_api.enabled");
}

export async function listAgents(): Promise<Agent[]> {
  const res = await fetch(`${getBackendBaseURL()}/api/agents`);
  if (!res.ok) throw new Error(`Failed to load agents: ${res.statusText}`);
  const data = (await res.json()) as { agents: Agent[] };
  return data.agents;
}

export async function getAgent(name: string): Promise<Agent> {
  const res = await fetch(`${getBackendBaseURL()}/api/agents/${name}`);
  if (!res.ok) throw new Error(`Agent '${name}' not found`);
  return res.json() as Promise<Agent>;
}

export async function createAgent(request: CreateAgentRequest): Promise<Agent> {
  const res = await fetch(`${getBackendBaseURL()}/api/agents`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(request),
  });
  if (!res.ok) {
    const err = (await res.json().catch(() => ({}))) as { detail?: string };
    if (isAgentsApiDisabledDetail(err.detail)) {
      throw new AgentsApiDisabledError(err.detail!);
    }
    throw new Error(err.detail ?? `Failed to create agent: ${res.statusText}`);
  }
  return res.json() as Promise<Agent>;
}

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Export the variable in the Gateway's real environment: export MEM0_API_KEY='...' or add it to docker-compose environment / systemd Environment=.
2. If you renamed api_key_env in backend_config, export the new name or revert it to MEM0_API_KEY.
3. Confirm the value is non-blank in the service context: printenv MEM0_API_KEY | wc -c.

Example fix

# before
# (nothing exported)
python -m app.gateway  # -> mem0 API key missing: MEM0_API_KEY

# after
export MEM0_API_KEY='m0-xxxxxxxxxxxxxxxx'
python -m app.gateway
# docker-compose.yml:
#   environment:
#     - MEM0_API_KEY=${MEM0_API_KEY}

import os


def require_env(name: str) -> str:
    value = os.environ.get(name, '').strip()
    if not value:
        raise SystemExit(f'Missing required environment variable: {name}')
    return value


require_env('MEM0_API_KEY')  # or your configured api_key_env

try:
    key = config.resolve_api_key()
except ValueError as e:
    # startup/config error: fail the deployment, do not retry
    raise SystemExit(f'mem0 credential not available: {e}')

When it happens

Trigger: Calling resolve_api_key() (it runs when the client needs to authenticate) while os.environ[api_key_env] is empty. Typical with fresh deploys, CI runners, containers started without the variable, or after renaming api_key_env in config without exporting the new name.

Common situations: Key exists in a local .env but the process runs under systemd/docker where .env is not loaded; api_key_env was customized (e.g. MEM0_PROD_KEY) but only MEM0_API_KEY is exported; the value is only whitespace after a bad copy-paste.

Related errors

• Failed to load agents: ${res.statusText}
• backend_unreachable
• request_failed
• Unable to recover SSE history after ${recoveryAttempts} atte
• Failed to submit feedback: ${res.status}

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/6fd135f7574cd74e. Report an issue: GitHub.