DoclingDocling for IBM watsonx

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-Key header
  • 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_position in 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_options without chunker. Always send "chunker": "hybrid" (or "hierarchical") explicitly. See Chunking.
  • A target that is not allowed for your sources. For example, presigned_url cannot be used when any source is a connector. See Convert Batch.
  • A wrong field type, such as page_range sent 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.

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.

For more help, consult the FAQ page or contact the support team.

On this page