{"record":{"id":"8e6b69d790cdc8d3","repo":"DioxusLabs/dioxus","slug":"backend-not-ready-after-max-wait-e","errorCode":null,"errorMessage":"Backend not ready after {max_wait:?}: {e}","messagePattern":"Backend not ready after (.+?): (.+?)","errorType":"http","errorClass":"anyhow::Error","httpStatus":500,"severity":"error","filePath":"packages/cli/src/serve/proxy.rs","lineNumber":42,"sourceCode":" url: &Uri,\n req: Request,\n handle_error: fn(Error) -> Response,\n) -> std::result::Result, Response> {\n let host = url.host().unwrap_or(\"127.0.0.1\");\n let port = url.port_u16().unwrap_or(80);\n let addr = format!(\"{host}:{port}\");\n\n let mut backoff = std::time::Duration::from_millis(100);\n let max_wait = std::time::Duration::from_secs(30);\n let start = std::time::Instant::now();\n\n // Retry TCP connect until backend is ready\n let stream = loop {\n match TcpStream::connect(&addr).await {\n Ok(stream) => break stream,\n Err(e) => {\n if start.elapsed() >= max_wait {\n return Err(handle_error(anyhow::anyhow!(\n \"Backend not ready after {max_wait:?}: {e}\"\n )));\n }\n tracing::debug!(\"Backend not ready, retrying in {backoff:?}...\");\n tokio::time::sleep(backoff).await;\n backoff = (backoff * 2).min(std::time::Duration::from_secs(2));\n }\n }\n };\n\n // Wrap the TCP stream for hyper\n let io = TokioIo::new(stream);\n\n // Perform HTTP/1.1 handshake on the same connection\n let (mut sender, conn) = http1::handshake(io)\n .await\n .map_err(|e| handle_error(anyhow::anyhow!(\"HTTP handshake failed: {e}\")))?;\n","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/DioxusLabs/dioxus/blob/393d190a801ccb441d41923e232289b4f8a5c669/packages/cli/src/serve/proxy.rs#L24-L60","documentation":"When [web.proxy] is configured, the dx dev server forwards matching requests to the backend via send_with_retry: it retries TCP connect with exponential backoff (100ms doubling, capped at 2s) for up to 30 seconds. If the backend still refuses connections after max_wait, the last io error is wrapped into this message and converted through handle_error into an error response for the browser.","triggerScenarios":"dx serve with a [web.proxy].backend that nothing is listening on for 30+ seconds — backend not started, crashed during startup, wrong host/port in Dioxus.toml, or container networking pointing at the wrong address.","commonSituations":"Forgetting to start the API server alongside dx serve; port mismatch after changing the backend's port; backend still compiling/booting when the first proxied request arrives; Docker service names not resolvable from the host.","solutions":["Start your backend and confirm it listens on the exact host:port from [web.proxy].backend","Fix the URL in Dioxus.toml (scheme + port) to match the running backend, e.g. backend = \"http://127.0.0.1:8080/api\"","Verify liveness independently: curl http://127.0.0.1:/ from the same machine","If the backend legitimately needs more than 30s to boot, delay loading proxied pages or request a configurable timeout upstream"],"exampleFix":"// Dioxus.toml — before: backend on 3000, but the API runs on 8080\n[web.proxy]\nbackend = \"http://127.0.0.1:3000/api\"\n\n// after\n[web.proxy]\nbackend = \"http://127.0.0.1:8080/api\"","handlingStrategy":"retry","validationCode":"# Prove the backend is up before dx serve (or before opening the page)\nfor i in $(seq 1 50); do curl -fsf http://127.0.0.1:8080/api >/dev/null && break; done; curl -fsf http://127.0.0.1:8080/api >/dev/null || echo 'backend down — fix before proxying'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Start the backend before dx serve, or use a process manager that boots both","Keep [web.proxy].backend host:port in lockstep with the backend's configured listener","Add a /health endpoint to the backend and probe it in dev scripts"],"tags":["cli","dev-server","proxy","network"],"backgroundTag":null,"analyzedSha":"393d190a801ccb441d41923e232289b4f8a5c669","analyzedAt":"2026-08-16T11:27:45.815Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}