datawhalechina/hello-agents · error

Failed to start session: ${response.statusText}

Error message

Failed to start session: ${response.statusText}

What it means

Thrown by startSession() in the SentenceExpandAgent frontend when POST /api/session/start returns a non-OK status. startSession bootstraps every expansion session, so this error blocks the entire manual/auto expansion flow. It reports response.statusText (e.g. 'Internal Server Error'), which is often empty in HTTP/2 — making the message just 'Failed to start session: '.

Source

Thrown at Co-creation-projects/xujikai-SentenceExpandAgent/frontend/src/api/expand.ts:30

} from '../types/expand';

// API 基础 URL
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000';

/**
 * 开始新的扩写会话
 */
export async function startSession(request: StartRequest): Promise<AgentResponse> {
  const response = await fetch(`${API_BASE_URL}/api/session/start`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(request),
  });

  if (!response.ok) {
    throw new Error(`Failed to start session: ${response.statusText}`);
  }

  return response.json();
}

/**
 * 提交用户扩写句子（手动模式）
 */
export async function submitSentence(request: SubmitRequest): Promise<AgentResponse> {
  const response = await fetch(`${API_BASE_URL}/api/session/submit`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(request),
  });

  if (!response.ok) {

View on GitHub (pinned to 606a07d341)

Solutions

1. Open DevTools > Network and check the actual status and response body of the /api/session/start call.
2. Verify API_BASE_URL and/or the dev-server proxy config points to the running backend port.
3. Confirm the StartRequest payload matches the backend schema (all required fields, correct types).
4. Include status and body in the error instead of statusText, which is frequently empty (see exampleFix).

Example fix

// before
if (!response.ok) {
  throw new Error(`Failed to start session: ${response.statusText}`);
}

// after
if (!response.ok) {
  const body = await response.text().catch(() => "");
  throw new Error(`Failed to start session: ${response.status} ${body.slice(0, 200)}`);
}

if (!request || typeof request !== 'object') {
  throw new Error('StartRequest is required');
}
// Align with backend schema, e.g.:
if (request.mode && !['manual', 'auto'].includes(request.mode)) {
  throw new Error(`mode must be 'manual' or 'auto'`);
}

function isStartRequest(r: unknown): r is StartRequest {
  return typeof r === 'object' && r !== null && 'mode' in r;
}

try {
  const resp = await startSession(request);
} catch (err) {
  const msg = (err as Error).message;
  if (msg.includes('404') || msg.includes('502')) hintBackendDown();
  else if (msg.includes('422')) hintPayloadMismatch();
  else showError(msg);
}

When it happens

Trigger: POST {API_BASE_URL}/api/session/start with a StartRequest body returns 404 (wrong API_BASE_URL or route not mounted), 422 (StartRequest missing required fields per backend schema), 500 (LLM/API-key failure while initializing the session), or a proxy 502 when the backend service is down.

Common situations: API_BASE_URL misconfigured or relying on a Vite proxy that isn't set up for /api; backend FastAPI process not running; required request fields (e.g. mode or text) omitted; statusText empty under HTTP/2 leaving a bare error message.

Related errors

• 计划模式请求失败: ${resp.status}
• Failed to submit sentence: ${response.statusText}
• 大纲生成失败:
• 请求失败
• 研究请求失败，状态码：${response.status}

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/a39608659a43c631. Report an issue: GitHub.