{"record":{"id":"ddadd0e697c65638","repo":"anthropics/skills","slug":"server-failed-to-start-on-port-server-port-wi","errorCode":null,"errorMessage":"Server failed to start on port {server['port']} within {args.timeout}s","messagePattern":"Server failed to start on port (.+?) within (.+?)s","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"skills/webapp-testing/scripts/with_server.py","lineNumber":80,"sourceCode":"\n    try:\n        # Start all servers\n        for i, server in enumerate(servers):\n            print(f\"Starting server {i+1}/{len(servers)}: {server['cmd']}\")\n\n            # Use shell=True to support commands with cd and &&\n            process = subprocess.Popen(\n                server['cmd'],\n                shell=True,\n                stdout=subprocess.PIPE,\n                stderr=subprocess.PIPE\n            )\n            server_processes.append(process)\n\n            # Wait for this server to be ready\n            print(f\"Waiting for server on port {server['port']}...\")\n            if not is_server_ready(server['port'], timeout=args.timeout):\n                raise RuntimeError(f\"Server failed to start on port {server['port']} within {args.timeout}s\")\n\n            print(f\"Server ready on port {server['port']}\")\n\n        print(f\"\\nAll {len(servers)} server(s) ready\")\n\n        # Run the command\n        print(f\"Running: {' '.join(args.command)}\\n\")\n        result = subprocess.run(args.command)\n        sys.exit(result.returncode)\n\n    finally:\n        # Clean up all servers\n        print(f\"\\nStopping {len(server_processes)} server(s)...\")\n        for i, process in enumerate(server_processes):\n            try:\n                process.terminate()\n                process.wait(timeout=5)\n            except subprocess.TimeoutExpired:","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/anthropics/skills/blob/f6656c1256d5a8adfa37db9110046ef20bac644c/skills/webapp-testing/scripts/with_server.py#L62-L98","documentation":"with_server.py starts one or more dev servers via shell commands and polls each port with is_server_ready(); if the port never accepts connections within --timeout seconds it raises this RuntimeError. The named port identifies which server['cmd'] failed to become reachable.","triggerScenarios":"Passing a server command that exits immediately (bad flag, missing dependency) so nothing ever listens; the server binding to a different port than server['port']; slow cold starts (first install/compile) exceeding args.timeout; the port already occupied by a stale process so the new server aborts.","commonSituations":"Local dev where npm install/dev-server startup exceeds the default timeout; server bound to 127.0.0.1 vs 0.0.0.0 mismatch with the readiness probe; port conflicts from a previous unclean run; wrong port number in the JSON/CLI config given to with_server.py.","solutions":["Run the server command exactly as passed to with_server.py in a separate terminal and watch it bind — confirm the port matches server['port']","Raise the budget: pass a larger --timeout (e.g. --timeout 120) for cold starts","Free a occupied port: `lsof -ti :PORT | xargs kill` (or pick another port)","Fix the server command so it listens on the expected interface/port (e.g. --host 127.0.0.1 --port 3000)"],"exampleFix":"# before\npython scripts/with_server.py --port 3000 -- npm run dev -- ./tests\n# after: longer budget and explicit matching port\npython scripts/with_server.py --port 3000 --timeout 120 -- npm run dev -- --port 3000 -- ./tests","handlingStrategy":"validation","validationCode":"import socket\n\ndef port_free(port: int) -> bool:\n    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:\n        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)\n        return s.connect_ex((\"127.0.0.1\", port)) != 0","typeGuard":null,"tryCatchPattern":"try:\n    run_with_server(servers, cmd, timeout=120)\nexcept RuntimeError as e:\n    if \"failed to start\" in str(e):\n        dump_server_logs()  # capture the Popen stdout/stderr you piped\n    raise","preventionTips":["Give CI/dev cold starts a generous --timeout","Assert the port is free before launching, and kill stale listeners afterwards","Make the server command's --port argument come from the same config as server['port'] so they can never diverge"],"tags":["dev-server","timeout","port","subprocess","testing"],"backgroundTag":null,"analyzedSha":"f6656c1256d5a8adfa37db9110046ef20bac644c","analyzedAt":"2026-08-14T16:09:17.493Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}