Hybrid server is not available at http://localhost:5002

[minhquoctran2604]

not available but I already started, I use in colab
INFO: 127.0.0.1:55288 - "POST /v1/convert/file HTTP/1.1" 200 OK

[hnc-jglee]

Thanks for reporting this! Based on the log you shared, your hybrid server is actually working correctly — the 200 OK response confirms successful PDF conversion.

The error message "Hybrid server is not available at http://localhost:5002" comes from the Java client's health check (GET /health), which runs with a 3-second timeout before any conversion request. There are a few common causes in Colab:

1. Server not fully initialized yet

The hybrid server needs time to load AI models (can take 30-60 seconds on first run). Wait for this log line before running the client:

INFO: DocumentConverter initialized in X.XXs

2. Timing issue

If you're starting the server and client in the same notebook, add a delay:

import time
time.sleep(10)  # Wait for server to fully start

Or better, check the health endpoint first:

import requests
while True:
    try:
        r = requests.get("http://127.0.0.1:5002/health", timeout=5)
        if r.status_code == 200:
            break
    except:
        pass
    time.sleep(2)

3. Use explicit IP instead of localhost

In some Colab environments, localhost may not resolve correctly. Try:

--hybrid-url http://127.0.0.1:5002

Could you share more details?

• The full error message (not just the server log)
• Your Colab notebook setup — how you start the server and client
• The server startup logs (from opendataloader-pdf-hybrid command)

This will help us pinpoint the exact cause.

[minhquoctran2604]

log_server.txt
log_client.txt

[hnc-jglee]

Thanks for sharing the logs! Now the root cause is clear.

Analysis

Server log

• Server started successfully on CPU (no GPU detected)
• Server is listening on http://0.0.0.0:5002 and working correctly

Client log — the real problem

1. First file (7-CNWeb-PHP-MVC.pdf): Processing timed out after 30 seconds (default --hybrid-timeout). On CPU-only, docling's layout analysis + table detection is very slow.
2. Subsequent files (5-CNWeb-PHP-Form.pdf, 8-CNWeb-PHP-Laravel.pdf): Got Connection refused — likely the server became unresponsive after the heavy first request.

Root cause

CPU-only processing + default 30s timeout is too short. Docling's AI models (layout detection, OCR, table structure) are designed for GPU. On CPU, a single page can take 10-30 seconds, so a 9-page PDF easily exceeds 30 seconds.

Solution

Increase the timeout significantly for CPU-only environments:

opendataloader-pdf --hybrid docling-fast --hybrid-timeout 300000 --hybrid-fallback file1.pdf file2.pdf

• --hybrid-timeout 300000 → 5 minutes (instead of default 30s)
• --hybrid-fallback → if backend still times out, fall back to Java processing instead of failing

For best performance in Colab

If your Colab instance has a GPU (Runtime → Change runtime type → T4 GPU), the server will auto-detect it and run much faster. You should see this in server logs:

GPU detected: Tesla T4 (CUDA 12.x)

Instead of:

Could not find cuda drivers on your machine, GPU will not be used.

Let me know if increasing the timeout resolves the issue!

[bundolee]

🤖 AI Issue Fix — status: triaged

Classification: user environment/configuration issue (CPU-only Colab + default 30s timeout).
Root cause identified by @hnc-jglee in previous comments. No code bug found.
Potential enhancement: auto-adjust timeout based on GPU detection (separate issue if needed).

---

Thank you for reporting this. As the analysis above shows, your hybrid server was actually working — the issue was that the default 30-second timeout is too short for CPU-only environments like Colab without GPU.

The solution shared by @hnc-jglee should resolve your problem: use --hybrid-timeout 300000 to allow 5 minutes per request, and consider enabling GPU in Colab for significantly faster processing. If you continue to experience issues after adjusting the timeout, please let us know!

[bundolee]

🤖 AI Issue Fix — status: resolved

PR #337 changes the default --hybrid-timeout from 30s to unlimited (0 = no timeout).
Users who need a timeout can explicitly set --hybrid-timeout <ms>.

---

Update: We have submitted PR #337 which changes the default --hybrid-timeout to unlimited (no timeout). This means the server will wait as long as needed for processing to complete, regardless of CPU/GPU environment. If you need to set a specific timeout, you can still do so explicitly with --hybrid-timeout <milliseconds>.

[minhquoctran2604]

Docling incorrectly splits Vietnamese diacritics with spaces - causing severe text corruption
How to fix this? 😢

[bundolee]

Hi @minhquoctran2604

For the Vietnamese diacritics problem, could you open a separate issue? It’ll be easier to track and investigate independently.

When you do, please include a sample PDF that reproduces the issue — or send it to open.dataloader@hancom.com and we’ll reference it internally.