Troubleshooting
Common issues and solutions for Docling for IBM watsonx
Troubleshooting
I am getting an "Invalid API Key" error
- Verify your API Key is correct
- Check that you're using the
X-Api-Keyheader - Check that the Service URL includes your instance ID, exactly as shown in the Workbench
My conversion has failed
- Check the error message in the status response
- Verify your document format is supported
- Ensure the document is not corrupted
My conversion is stuck in "pending"
Possible reasons:
- High system load - Check
task_positionin status response - Large document - Complex documents take longer
- Network issues - Verify connectivity to the service
If your request is at the top of the queue and taking longer than 5 minutes, contact support with the task_id.
I am getting a "Task result not found" error
This means:
- Conversion is still in progress (check status first)
- Task has expired (results are kept for 24 hours)
- Invalid
task_id(verify you're using the correct ID)
Always check the status endpoint before retrieving results.
I am getting a 422 validation error
The request body doesn't match the expected shape. The response lists the offending fields. Common causes:
chunking_optionswithoutchunker. Always send"chunker": "hybrid"(or"hierarchical") explicitly. See Chunking.- A target that is not allowed for your sources. For example,
presigned_urlcannot be used when any source is a connector. See Convert Batch. - A wrong field type, such as
page_rangesent as a string instead of[first, last].
My batch task succeeded, but some documents are missing
A task can succeed while individual documents fail. Check num_failed and num_partially_succeeded in the result, and the status and errors of each document. Typical causes are unsupported or corrupted files, and documents that exceed a size or time limit.
A connector cannot read or write
- Credentials. Check that the keys or secrets are valid and not expired, and that they have read access on the source and write access on the target.
- Network reachability. The service connects to your system from IBM Cloud. Private endpoints, IP allow lists or VPN-only clusters must allow that traffic.
- Kafka. Create the topic before you submit. Docling does not create topics. For clusters with a private CA, pass
ca_cert. See Kafka.
My download link stopped working
Download URLs in results expire at url_expires_at. Download artifacts promptly, or deliver results to your own storage with a connector target.
I am observing low quality in the output
Possible causes and solutions:
- Low-resolution source - Use higher quality scans (300+ DPI)
- Unsupported format - Verify file format is supported
- Corrupted file - Test if your file opens in native application
If issues persist, contact support with sample documents.