{"record":{"id":"07a07c3b4701a71e","repo":"oobabooga/textgen","slug":"could-not-start-cloudflared","errorCode":null,"errorMessage":"Could not start cloudflared.","messagePattern":"Could not start cloudflared\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"modules/api/utils.py","lineNumber":53,"sourceCode":"        raise Exception(\n            'flask_cloudflared not installed. Make sure you installed the requirements.txt for this extension.')\n\n    for _ in range(max_attempts):\n        try:\n            if tunnel_id is not None:\n                public_url = _run_cloudflared(port, port + 1, tunnel_id=tunnel_id)\n            else:\n                public_url = _run_cloudflared(port, port + 1)\n\n            if on_start:\n                on_start(public_url)\n\n            return\n        except Exception:\n            traceback.print_exc()\n            time.sleep(3)\n\n    raise Exception('Could not start cloudflared.')\n","sourceCodeStart":35,"sourceCodeEnd":54,"githubUrl":"https://github.com/oobabooga/textgen/blob/ed888c71f221df552750e1834b3654abab8ae345/modules/api/utils.py#L35-L54","documentation":"Raised by _start_cloudflared (modules/api/utils.py:53) after max_attempts (default 3) consecutive failures of _run_cloudflared — the cloudflared binary ran but could not establish a tunnel (no route to Cloudflare edge, invalid/already-bound ports, tunnel_id rejected, missing binary). Each attempt's traceback is printed and the loop sleeps 3s before retrying.","triggerScenarios":"Launching with --public-api (optionally --public-api-id) on a machine with no outbound connectivity to Cloudflare edge (port 7844 blocked), where cloudflared is not installed/downloadable, or the local metrics port (port+1) is already in use by a previous cloudflared instance.","commonSituations":"Firewalled/containerized environments blocking QUIC/TCP to Cloudflare; stale cloudflared process holding the tunnel or ports; offline machines; repeated starts leaving orphaned tunnel processes.","solutions":["Check the printed tracebacks of all 3 attempts — they distinguish network failure from binary/port issues.","Ensure outbound TCP:7844 (and DNS) to Cloudflare is allowed; on restricted networks try cloudflared's --edge-ip-version or HTTP/2 fallback.","Kill stale cloudflared processes (pkill cloudflared) so ports port/port+1 are free, then retry.","If tunnels are systematically blocked, drop --public-api and expose via --listen + your own proxy."],"exampleFix":"# before\npython server.py --api --public-api   # retries 3x, then: Could not start cloudflared.\n\n# after\npkill -f cloudflared\npython server.py --api --listen   # LAN exposure without tunnel\n","handlingStrategy":"retry","validationCode":"import socket, subprocess\n\ndef tunnel_prereqs_ok(port: int) -> bool:\n    # local ports free\n    for p in (port, port + 1):\n        with socket.socket() as s:\n            try:\n                s.bind(('0.0.0.0', p))\n            except OSError:\n                return False\n    return True\n","typeGuard":null,"tryCatchPattern":"for attempt in range(3):\n    if start_server_with_public_api():\n        break\n    pkill_cloudflared()\n    time.sleep(3)\nelse:\n    fall_back_to_lan_listen()  # run without --public-api\n","preventionTips":["Kill orphaned cloudflared processes before each public-API start.","Verify outbound connectivity to Cloudflare (tcp/7844) in firewalled environments.","Treat public tunnels as best-effort: keep a --listen fallback path in your runbook."],"tags":["public-api","cloudflared","network","tunnel"],"backgroundTag":null,"analyzedSha":"ed888c71f221df552750e1834b3654abab8ae345","analyzedAt":"2026-08-15T05:24:21.000Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}