opendataloader-project/opendataloader-pdf · error · IOException

Hybrid server is not available at %s To start the local hybr

Error message

Hybrid server is not available at %s
To start the local hybrid server:
  1. Install: pip install "opendataloader-pdf[hybrid]"
  2. Start:   opendataloader-pdf-hybrid --port 5002
To use a remote server or custom port: --hybrid-url http://host:port
Or pass --hybrid-fallback to fall back to Java-only output for this run.
Or run without --hybrid flag for Java-only processing.

What it means

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.

Source

Thrown at java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/DoclingFastServerClient.java:114

    }

    @Override
    public void checkAvailability() throws IOException {
        OkHttpClient healthClient = httpClient.newBuilder()
            .connectTimeout(HEALTH_CHECK_TIMEOUT_MS, TimeUnit.MILLISECONDS)
            .readTimeout(HEALTH_CHECK_TIMEOUT_MS, TimeUnit.MILLISECONDS)
            .build();

        Request healthRequest = new Request.Builder()
            .url(baseUrl + HEALTH_ENDPOINT)
            .get()
            .build();

        Response response;
        try {
            response = healthClient.newCall(healthRequest).execute();
        } catch (IOException e) {
            throw new IOException(
                "Hybrid server is not available at " + baseUrl + "\n"
                + "To start the local hybrid server:\n"
                + "  1. Install: pip install \"opendataloader-pdf[hybrid]\"\n"
                + "  2. Start:   opendataloader-pdf-hybrid --port 5002\n"
                + "To use a remote server or custom port: --hybrid-url http://host:port\n"
                + "Or pass --hybrid-fallback to fall back to Java-only output for this run.\n"
                + "Or run without --hybrid flag for Java-only processing.", e);
        }
        try (response) {
            if (!response.isSuccessful()) {
                throw new IOException(
                    "Hybrid server at " + baseUrl + " returned HTTP " + response.code()
                    + " during health check.\n"
                    + "The server is reachable but may be starting up or unhealthy.");
            }
        }
    }

View on GitHub (pinned to a7789b8e77)

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

Example fix

// before
opendataloader-pdf --hybrid=docling-fast in.pdf
// after
opendataloader-pdf --hybrid=docling-fast --hybrid-fallback in.pdf

Defensive patterns

Strategy: fallback

Validate before calling

// Probe the server before configuring hybrid
try (java.net.Socket s = new java.net.Socket()) {
    s.connect(new InetSocketAddress(host, port), 1000);
} catch (IOException e) {
    // server not listening — fall back to Java-only
    config.setHybrid(null);
}

Try / catch

try {
    client.checkAvailability();
} catch (IOException e) {
    // e.getMessage() includes the setup instructions
    log.warn("hybrid unavailable, using Java-only: {}", e.getMessage());
    config.getHybridConfig().setFallbackToJava(true);
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of opendataloader-project/opendataloader-pdf@a7789b8e77 (2026-08-14). Data as JSON: /api/errors/118720094df0dbb2. Report an issue: GitHub.