{"record":{"id":"ec7463fe99f24314","repo":"PrefectHQ/fastmcp","slug":"user-server-did-not-start-on-port-mcp-port","errorCode":null,"errorMessage":"User server did not start on port {mcp_port}","messagePattern":"User server did not start on port (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/cli/apps_dev.py","lineNumber":1812,"sourceCode":"        logger.info(\"Fetching app-bridge.js from npm…\")\n\n        # Start the server first so user_proc is assigned before anything\n        # that might fail (e.g. npm fetch).  This ensures the finally\n        # cleanup can kill the subprocess even if the bundle fetch raises.\n        user_proc = await _start_user_server(\n            server_spec, mcp_port, reload=reload, host=host\n        )\n        app_bridge_js, import_map_json = await _fetch_app_bridge_bundle(\n            _EXT_APPS_VERSION, _MCP_SDK_VERSION\n        )\n\n        import_map_tag = (\n            f'  <script type=\"importmap\">\\n  {import_map_json}\\n  </script>'\n        )\n\n        ready = await _wait_for_server(mcp_url, timeout=15.0)\n        if not ready:\n            raise RuntimeError(f\"User server did not start on port {mcp_port}\")\n\n        logger.info(f\"FastMCP dev UI at {dev_url}\")\n\n        dev_app = _make_dev_app(\n            mcp_url, app_bridge_js, import_map_tag, _MessageLog(), log_panel\n        )\n        config = uvicorn.Config(\n            dev_app,\n            host=host,\n            port=dev_port,\n            log_level=\"warning\",\n            ws=\"websockets-sansio\",\n        )\n        server = uvicorn.Server(config)\n        # Suppress uvicorn's own signal handlers — they use signal.signal() which\n        # conflicts with asyncio and causes hangs.  We cancel the task instead.\n        server.install_signal_handlers = lambda: None  # type: ignore[method-assign]  # ty:ignore[unresolved-attribute]\n","sourceCodeStart":1794,"sourceCodeEnd":1830,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/cli/apps_dev.py#L1794-L1830","documentation":"`fastmcp dev` for apps starts the dev UI only after the user's MCP server answers on the configured port. _wait_for_server polls for up to 15 seconds; if the server never becomes reachable, run_dev_apps raises this RuntimeError naming the port. It is a startup-failure guard, not a runtime crash of your server code.","triggerScenarios":"The MCP server process failed to boot (import error, bad config, port already bound by another process), or it listens on a different host/port than mcp_url expects, and the 15s poll times out.","commonSituations":"Syntax/import error in the user's server module; another process occupying the port; server bound to 0.0.0.0:9999 while the dev UI probes a different port; slow imports (heavy ML libs) exceeding the 15s timeout.","solutions":["Run your server directly (e.g. fastmcp run or python your_server.py) to see the actual boot error","Check the port isn't already in use (lsof -i :PORT) and kill the stale process","Confirm host/port match between your server binding and the dev command's mcp_port","If the server just starts slowly, increase the timeout or pre-warm imports"],"exampleFix":"# before: server binds elsewhere\nmcp.run(host='0.0.0.0', port=9999)  # dev expects 8000\n# after\nmcp.run(host='127.0.0.1', port=8000)","handlingStrategy":"retry","validationCode":"import socket\ns = socket.socket()\ns.settimeout(2)\ntry:\n    s.connect(('127.0.0.1', mcp_port)); print('port in use')\nexcept OSError:\n    print('port free; server not running yet')\nfinally:\n    s.close()","typeGuard":null,"tryCatchPattern":"try:\n    run_dev_apps(...)\nexcept RuntimeError as exc:\n    if str(exc).startswith('User server did not start'):\n        logger.error('MCP server failed to boot; run it directly to see the underlying error')\n    else:\n        raise","preventionTips":["Boot your server standalone before running the dev UI","Check for port conflicts with lsof/netstat","Keep server module imports light to stay under the 15s startup timeout","Confirm the dev command's port matches your server's binding"],"tags":["network","startup","timeout","dev-server","port"],"backgroundTag":"server-startup-timeout","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}