{"record":{"id":"d238e8eca1065133","repo":"sipeed/picoclaw","slug":"failed-to-start-gateway-v","errorCode":null,"errorMessage":"Failed to start gateway: %v","messagePattern":"Failed to start gateway: (.+?)","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"web/backend/api/gateway.go","lineNumber":1249,"sourceCode":"\t\t\tw,\n\t\t\tfmt.Sprintf(\"Failed to validate gateway start conditions: %v\", err),\n\t\t\thttp.StatusInternalServerError,\n\t\t)\n\t\treturn\n\t}\n\tif !ready {\n\t\tw.Header().Set(\"Content-Type\", \"application/json\")\n\t\tw.WriteHeader(http.StatusBadRequest)\n\t\tjson.NewEncoder(w).Encode(map[string]any{\n\t\t\t\"status\":  \"precondition_failed\",\n\t\t\t\"message\": reason,\n\t\t})\n\t\treturn\n\t}\n\n\tpid, err := h.startGatewayLocked(\"starting\", 0)\n\tif err != nil {\n\t\thttp.Error(w, fmt.Sprintf(\"Failed to start gateway: %v\", err), http.StatusInternalServerError)\n\t\treturn\n\t}\n\n\tw.Header().Set(\"Content-Type\", \"application/json\")\n\tjson.NewEncoder(w).Encode(map[string]any{\n\t\t\"status\": \"ok\",\n\t\t\"pid\":    pid,\n\t})\n}\n\n// handleGatewayStop stops the running gateway subprocess gracefully.\n// Note: Unlike StopGateway (which only stops self-started processes), this API endpoint\n// stops any gateway process, including attached ones. This is intentional for user control.\n//\n//\tPOST /api/gateway/stop\nfunc (h *Handler) handleGatewayStop(w http.ResponseWriter, r *http.Request) {\n\tgateway.mu.Lock()\n\tdefer gateway.mu.Unlock()","sourceCodeStart":1231,"sourceCodeEnd":1267,"githubUrl":"https://github.com/sipeed/picoclaw/blob/49183d7e8daed0dba89ddbb6fcb60089401d9680/web/backend/api/gateway.go#L1231-L1267","documentation":"Returned by POST /api/gateway/start when h.startGatewayLocked(\"starting\", 0) fails to spawn a new gateway subprocess. Reading gateway.go:1008-1061, failure points are: config.LoadConfig (wrapped as 'failed to load config'), utils.FindPicoclawBinary() not locating the picoclaw executable, StdoutPipe/StderrPipe creation failing (usually fd exhaustion), or cmd.Start failing (exec format error, fork failure, missing binary). The wrapped %v identifies which stage died.","triggerScenarios":"picoclaw binary not on PATH and not beside the launcher binary (FindPicoclawBinary returns nothing usable); fd limit (ulimit -n) exhausted so pipe creation fails; exec bit lost after copying the binary; config file unreadable (wrapped 'failed to load config').","commonSituations":"Running the web backend from a different working directory or container image that omits the gateway binary; upgrading picoclaw and leaving a renamed/removed old binary; CI or constrained environments with low fd limits.","solutions":["Read the wrapped message: 'failed to load config' -> fix the config file (see error 902); pipe errors -> raise fd limits; exec errors -> fix the binary","Ensure the picoclaw executable exists, is installed next to the launcher or on PATH, and has the execute bit set","Check 'ulimit -n' and raise it if StdoutPipe/StderrPipe creation is failing","Retry POST /api/gateway/start after fixing the underlying cause"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"const res = await fetch('/api/gateway/start', {method: 'POST'});\nif (!res.ok) {\n  const text = await res.text();\n  if (text.includes('failed to load config')) throw new Error('Config file broken - repair it first');\n  if (text.includes('pipe')) throw new Error('OS fd limit hit - raise ulimit -n and restart the backend');\n  if (text.includes('picoclaw') || text.toLowerCase().includes('executable')) throw new Error('picoclaw binary not found - reinstall or fix PATH');\n  throw new Error(text);\n}","preventionTips":["Verify the picoclaw binary is installed beside the launcher or on PATH as part of deployment checks","Monitor fd usage on long-running backends; pipes are created per gateway start","Check exec bits after copying binaries between hosts or into containers"],"tags":["gateway","process","exec","go","subprocess"],"backgroundTag":null,"analyzedSha":"49183d7e8daed0dba89ddbb6fcb60089401d9680","analyzedAt":"2026-08-15T21:55:41.315Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}