{"record":{"id":"118720094df0dbb2","repo":"opendataloader-project/opendataloader-pdf","slug":"hybrid-server-is-not-available-at-s-to-start-the","errorCode":null,"errorMessage":"Hybrid server is not available at %s\nTo start the local hybrid server:\n  1. Install: pip install \"opendataloader-pdf[hybrid]\"\n  2. Start:   opendataloader-pdf-hybrid --port 5002\nTo use a remote server or custom port: --hybrid-url http://host:port\nOr pass --hybrid-fallback to fall back to Java-only output for this run.\nOr run without --hybrid flag for Java-only processing.","messagePattern":"Hybrid server is not available at (.+?)\nTo start the local hybrid server:\n  1\\. Install: pip install \"opendataloader-pdf\\[hybrid\\]\"\n  2\\. Start:   opendataloader-pdf-hybrid --port 5002\nTo use a remote server or custom port: --hybrid-url http://host:port\nOr pass --hybrid-fallback to fall back to Java-only output for this run\\.\nOr run without --hybrid flag for Java-only processing\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java","lineNumber":114,"sourceCode":"    }\n\n    @Override\n    public void checkAvailability() throws IOException {\n        OkHttpClient healthClient = httpClient.newBuilder()\n            .connectTimeout(HEALTH_CHECK_TIMEOUT_MS, TimeUnit.MILLISECONDS)\n            .readTimeout(HEALTH_CHECK_TIMEOUT_MS, TimeUnit.MILLISECONDS)\n            .build();\n\n        Request healthRequest = new Request.Builder()\n            .url(baseUrl + HEALTH_ENDPOINT)\n            .get()\n            .build();\n\n        Response response;\n        try {\n            response = healthClient.newCall(healthRequest).execute();\n        } catch (IOException e) {\n            throw new IOException(\n                \"Hybrid server is not available at \" + baseUrl + \"\\n\"\n                + \"To start the local hybrid server:\\n\"\n                + \"  1. Install: pip install \\\"opendataloader-pdf[hybrid]\\\"\\n\"\n                + \"  2. Start:   opendataloader-pdf-hybrid --port 5002\\n\"\n                + \"To use a remote server or custom port: --hybrid-url http://host:port\\n\"\n                + \"Or pass --hybrid-fallback to fall back to Java-only output for this run.\\n\"\n                + \"Or run without --hybrid flag for Java-only processing.\", e);\n        }\n        try (response) {\n            if (!response.isSuccessful()) {\n                throw new IOException(\n                    \"Hybrid server at \" + baseUrl + \" returned HTTP \" + response.code()\n                    + \" during health check.\\n\"\n                    + \"The server is reachable but may be starting up or unhealthy.\");\n            }\n        }\n    }\n","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/opendataloader-project/opendataloader-pdf/blob/a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java#L96-L132","documentation":"DoclingFastServerClient.checkAvailability issues a GET to the /health endpoint with a 3s timeout; if that call throws IOException (connection refused, DNS failure, timeout), the client wraps it with actionable setup instructions. It means the docling-fast-server is not reachable at baseUrl at all — no TCP connection was established.","triggerScenarios":"The health-check GET to baseUrl + '/health' raises IOException within HEALTH_CHECK_TIMEOUT_MS (3000ms): nothing listening on the port, wrong host/port, firewall block, DNS resolution failure, or the server process not started.","commonSituations":"Forgetting to start opendataloader-pdf-hybrid; pointing --hybrid-url at the wrong port (default 5002); the hybrid extra not installed; Docker/network isolation between the Java process and the server container; server still booting past the connect timeout.","solutions":["Start the local server: pip install \"opendataloader-pdf[hybrid]\" then opendataloader-pdf-hybrid --port 5002","Pass the correct address via --hybrid-url http://host:port","Add --hybrid-fallback to degrade to Java-only output for this run","Run without --hybrid for Java-only processing","Verify connectivity: curl http://localhost:5002/health"],"exampleFix":"// before\nopendataloader-pdf --hybrid=docling-fast in.pdf\n// after\nopendataloader-pdf --hybrid=docling-fast --hybrid-fallback in.pdf","handlingStrategy":"fallback","validationCode":"// Probe the server before configuring hybrid\ntry (java.net.Socket s = new java.net.Socket()) {\n    s.connect(new InetSocketAddress(host, port), 1000);\n} catch (IOException e) {\n    // server not listening — fall back to Java-only\n    config.setHybrid(null);\n}","typeGuard":null,"tryCatchPattern":"try {\n    client.checkAvailability();\n} catch (IOException e) {\n    // e.getMessage() includes the setup instructions\n    log.warn(\"hybrid unavailable, using Java-only: {}\", e.getMessage());\n    config.getHybridConfig().setFallbackToJava(true);\n}","preventionTips":["Always pass --hybrid-fallback in batch jobs so one missing server doesn't abort the batch","Keep the hybrid server address in a single env var / config to avoid port mismatches","Run opendataloader-pdf-hybrid as a supervised service that auto-restarts"],"tags":["network","hybrid","docling-fast","connection","health-check"],"backgroundTag":null,"analyzedSha":"a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8","analyzedAt":"2026-08-14T05:22:03.953Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}