bytedance/deer-flow · error · AgentNameCheckError

backend_unreachable

backend_unreachable

Error message

Could not reach the DeerFlow backend.

What it means

Raised when the openviking api_key_env setting resolves to an empty string after strip(). api_key_env names the environment variable holding the USER API key (default OPENVIKING_API_KEY); an explicitly empty value means the config can never tell you which variable to export, so it fails fast before the environment is even consulted.

Source

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

}

export async function deleteAgent(name: string): Promise<void> {
  const res = await fetch(`${getBackendBaseURL()}/api/agents/${name}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error(`Failed to delete agent: ${res.statusText}`);
}

export async function checkAgentName(
  name: string,
): Promise<{ available: boolean; name: string }> {
  let res: Response;
  try {
    res = await fetch(
      `${getBackendBaseURL()}/api/agents/check?name=${encodeURIComponent(name)}`,
    );
  } catch {
    throw new AgentNameCheckError(
      "Could not reach the DeerFlow backend.",
      "backend_unreachable",
    );
  }

  if (!res.ok) {
    const err = (await res.json().catch(() => ({}))) as { detail?: string };
    if (isAgentsApiDisabledDetail(err.detail)) {
      throw new AgentsApiDisabledError(err.detail!);
    }
    if (BACKEND_UNAVAILABLE_STATUSES.has(res.status)) {
      throw new AgentNameCheckError(
        "Could not reach the DeerFlow backend.",
        "backend_unreachable",
      );
    }
    const backendDetail = typeof err.detail === "string" ? err.detail : null;
    throw new AgentNameCheckError(

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Set api_key_env to a real variable name, e.g. api_key_env: OPENVIKING_API_KEY.
2. Or delete the api_key_env line entirely to accept the default OPENVIKING_API_KEY.
3. If templating produced the empty value, fix the template so unset expansions fail loudly instead of collapsing to ''.

Example fix

# before
backend_config:
  api_key_env: ''

# after
backend_config:
  api_key_env: OPENVIKING_API_KEY

def check_api_key_env(value: str) -> str:
    name = value.strip()
    assert name, 'api_key_env must be a non-empty environment variable name'
    return name

When it happens

Trigger: Setting api_key_env: '' (or a whitespace-only value, or a template expansion like ${OV_KEY:-} that collapses to empty) in the openviking backend_config. The check runs during from_backend_config, so exporting the key does not help until the name is fixed.

Common situations: Templated YAML where an optional variable collapses to an empty string; deleting a value but leaving the key; copy-paste config where a placeholder was never filled in.

Related errors

• Agent '${name}' not found
• request_failed
• Unable to recover SSE history after ${recoveryAttempts} atte
• Failed to submit feedback: ${res.status}
• Failed to delete feedback: ${res.status}

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