{"record":{"id":"a39608659a43c631","repo":"datawhalechina/hello-agents","slug":"failed-to-start-session-response-statustext","errorCode":null,"errorMessage":"Failed to start session: ${response.statusText}","messagePattern":"Failed to start session: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"Co-creation-projects/xujikai-SentenceExpandAgent/frontend/src/api/expand.ts","lineNumber":30,"sourceCode":"} from '../types/expand';\n\n// API 基础 URL\nconst API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000';\n\n/**\n * 开始新的扩写会话\n */\nexport async function startSession(request: StartRequest): Promise<AgentResponse> {\n  const response = await fetch(`${API_BASE_URL}/api/session/start`, {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n    },\n    body: JSON.stringify(request),\n  });\n\n  if (!response.ok) {\n    throw new Error(`Failed to start session: ${response.statusText}`);\n  }\n\n  return response.json();\n}\n\n/**\n * 提交用户扩写句子（手动模式）\n */\nexport async function submitSentence(request: SubmitRequest): Promise<AgentResponse> {\n  const response = await fetch(`${API_BASE_URL}/api/session/submit`, {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n    },\n    body: JSON.stringify(request),\n  });\n\n  if (!response.ok) {","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/Co-creation-projects/xujikai-SentenceExpandAgent/frontend/src/api/expand.ts#L12-L48","documentation":"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: '.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Open DevTools > Network and check the actual status and response body of the /api/session/start call.","Verify API_BASE_URL and/or the dev-server proxy config points to the running backend port.","Confirm the StartRequest payload matches the backend schema (all required fields, correct types).","Include status and body in the error instead of statusText, which is frequently empty (see exampleFix)."],"exampleFix":"// before\nif (!response.ok) {\n  throw new Error(`Failed to start session: ${response.statusText}`);\n}\n\n// after\nif (!response.ok) {\n  const body = await response.text().catch(() => \"\");\n  throw new Error(`Failed to start session: ${response.status} ${body.slice(0, 200)}`);\n}","handlingStrategy":"try-catch","validationCode":"if (!request || typeof request !== 'object') {\n  throw new Error('StartRequest is required');\n}\n// Align with backend schema, e.g.:\nif (request.mode && !['manual', 'auto'].includes(request.mode)) {\n  throw new Error(`mode must be 'manual' or 'auto'`);\n}","typeGuard":"function isStartRequest(r: unknown): r is StartRequest {\n  return typeof r === 'object' && r !== null && 'mode' in r;\n}","tryCatchPattern":"try {\n  const resp = await startSession(request);\n} catch (err) {\n  const msg = (err as Error).message;\n  if (msg.includes('404') || msg.includes('502')) hintBackendDown();\n  else if (msg.includes('422')) hintPayloadMismatch();\n  else showError(msg);\n}","preventionTips":["Type the request with a shared schema (or zod) mirroring the backend model so 422s are caught at compile time.","Include response.status in thrown errors — statusText is empty under HTTP/2.","Health-check the backend before the first session call to fail with a clear message."],"tags":["http","fetch","api-client","session-init"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}