{"record":{"id":"1469398372b95362","repo":"opendataloader-project/opendataloader-pdf","slug":"hybrid-server-is-not-available-at-s-please-check","errorCode":null,"errorMessage":"Hybrid server is not available at %s\nPlease check the server URL and ensure the Hancom API is accessible.\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 (.+?)\nPlease check the server URL and ensure the Hancom API is accessible\\.\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":"critical","filePath":"java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/HancomClient.java","lineNumber":121,"sourceCode":"\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 request = new Request.Builder()\n            .url(baseUrl)\n            .head()\n            .build();\n\n        try (Response response = healthClient.newCall(request).execute()) {\n            // Any HTTP response (including 4xx/5xx) means the server is reachable.\n            // Hancom API requires authentication for all endpoints, so a 401/403\n            // is expected and still proves connectivity.\n        } catch (IOException e) {\n            throw new IOException(\n                \"Hybrid server is not available at \" + baseUrl + \"\\n\"\n                + \"Please check the server URL and ensure the Hancom API is accessible.\\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    }\n\n    @Override\n    public HybridResponse convert(HybridRequest request) throws IOException {\n        String fileId = null;\n        try {\n            // Step 1: Upload PDF\n            fileId = uploadFile(request.getPdfBytes());\n            LOGGER.log(Level.FINE, \"Uploaded file with ID: {0}\", fileId);\n\n            // Step 2: Get visual info\n            JsonNode visualInfo = getVisualInfo(fileId);\n            LOGGER.log(Level.FINE, \"Retrieved visual info for file: {0}\", fileId);","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/opendataloader-project/opendataloader-pdf/blob/a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/hybrid/HancomClient.java#L103-L139","documentation":"HancomClient.checkAvailability() sends a HEAD request to the base URL and any IOException (connection refused, DNS resolution failure, connect timeout, SSL handshake error) is caught and re-thrown with actionable guidance. A successful HTTP response of any status code (including 401/403) proves connectivity because the Hancom API requires authentication on all endpoints. This error means the server is entirely unreachable, not merely returning an error code.","triggerScenarios":"Calling HybridClient.checkAvailability() on a HancomClient when the server URL is wrong, the host is down, a firewall blocks the port, DNS cannot resolve the hostname, or the HEALTH_CHECK_TIMEOUT_MS window expires before the TCP connection establishes. Also triggered when an HTTPS URL is used but the server certificate is invalid or the TLS version is unsupported.","commonSituations":"Wrong --hybrid-url (typo, missing port, forgot /api path suffix); server not started yet; corporate VPN or firewall blocking outbound access to dataloader.cloud.hancom.com; using http:// against an HTTPS-only endpoint; DNS outage or stale cached entry pointing to a decommissioned IP.","solutions":["Verify the server URL with curl: `curl -I <url>` or `curl -sS -o /dev/null -w '%{http_code}' <url>` — any HTTP status code (even 401) confirms reachability.","Pass --hybrid-fallback to continue processing with Java-only output for this run while the server issue is investigated.","Drop the --hybrid flag entirely to run in pure Java mode without any availability check.","Check DNS resolution: `nslookup <hostname>` or `dig <hostname>` to rule out DNS failures.","If using a self-hosted Hancom instance, confirm the service is running and the port is open: `telnet <host> <port>` or `nc -zv <host> <port>`.","For HTTPS endpoints, verify certificate validity with `openssl s_client -connect <host>:443`."],"exampleFix":"// before: throws and aborts the whole run\nclient.checkAvailability();\n\n// after: graceful fallback to Java-only processing\ntry {\n    client.checkAvailability();\n} catch (IOException e) {\n    if (config.isFallbackToJava()) {\n        LOGGER.warning(\"Hybrid server unavailable, falling back to Java-only: \" + e.getMessage());\n        // proceed with Java-only pipeline\n    } else {\n        throw e;\n    }\n}","handlingStrategy":"fallback","validationCode":"// Validate reachability before starting hybrid processing\ntry {\n    client.checkAvailability();\n} catch (IOException e) {\n    if (config.isFallbackToJava()) {\n        LOGGER.warning(\"Hybrid unavailable, using Java-only mode\");\n        runJavaOnlyPipeline();\n        return;\n    }\n    throw e;\n}","typeGuard":null,"tryCatchPattern":"try {\n    client.checkAvailability();\n} catch (IOException e) {\n    // The error message already suggests --hybrid-fallback and removing --hybrid\n    if (config.isFallbackToJava()) {\n        proceedWithJavaOnly();\n    } else {\n        // Re-throw — the user must decide whether to fall back\n        throw e;\n    }\n}","preventionTips":["Always set --hybrid-fallback when running in production to avoid hard failures on network issues.","Use a health-check wrapper that retries checkAvailability with a short delay before giving up.","Configure OkHttp connectTimeout to fail fast rather than hanging on unreachable hosts.","Keep the server URL in a centralized config to avoid typos across deployments."],"tags":["network","hancom","hybrid","connectivity","configuration"],"backgroundTag":null,"analyzedSha":"a7789b8e77dd05e2b8659eb3ea12fc458f80bfb8","analyzedAt":"2026-08-14T05:22:03.953Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}