PaddlePaddle/PaddleOCR · error · InvalidRequestError

Either fileUrl or filePath is required.

Error message

Either fileUrl or filePath is required.

What it means

Raised as NetworkError from submit_url in paddleocr/_api_client/_http.py:122 when the POST to create a URL-based job fails at the connection layer (requests.ConnectionError): DNS resolution failure, refused connection, TLS handshake failure, or connection reset. The request never completed, so no job was created. Original exception is chained for diagnosis.

Solutions

1. Verify network connectivity: curl the API base URL from the same machine/container
2. Check the configured base URL for typos and correct region
3. Configure proxy env vars (HTTPS_PROXY) if behind a corporate proxy, or bypass it
4. Verify DNS resolution (nslookup/getent hosts <api-host>)
5. Retry — transient resets and DNS blips often clear immediately

Example fix

# diagnose
import requests
print(requests.get("https://<api-base>/", timeout=10).status_code)

# preflight connectivity before bulk runs
import requests
try:
    requests.head(api_base_url, timeout=5)
except requests.ConnectionError:
    print("API host unreachable — fix network/proxy first")

from paddleocr._api_client.errors import NetworkError
try:
    job_id = client.submit_url(model, file_url, {})
except NetworkError as e:
    logger.error("Cannot reach API: %s", e)
    raise

When it happens

Trigger: client.submit_url(...) with no internet, wrong/unresolvable API hostname, blocked port, corporate firewall or proxy rejecting the API host, or TLS interception failure.

Common situations: Offline or restricted CI environments; typo in base URL; DNS problems; firewall/geo-blocking of the API domain; expired corporate proxy credentials.

Related errors

• Document parsing result page is missing markdown.text.
• Model is not an OCR model.
• OCR result page is missing prunedResult.
• Unsafe resource filename
• Connection failed

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/b0d2f47b9c6719de. Report an issue: GitHub.

Appendix: source

Thrown at api_sdk/typescript/src/client.ts:253

        throw new InvalidRequestError(`Destination parent must be a directory: ${parent}`);
      }
    } catch (error) {
      if (error instanceof InvalidRequestError) {
        throw error;
      }
      throw new FileNotFoundError(parent, { cause: error });
    }
    return target;
  }

  private async submit(
    model: string,
    task: Job["task"],
    req: { fileUrl?: string; filePath?: string; pageRanges?: string; batchId?: string; options?: object },
    signal?: AbortSignal,
  ): Promise<string> {
    if (!req.fileUrl && !req.filePath) {
      throw new InvalidRequestError("Either fileUrl or filePath is required.");
    }
    if (req.fileUrl && req.filePath) {
      throw new InvalidRequestError("fileUrl and filePath are mutually exclusive.");
    }

    this.validateModelForTask(model, task);
    const payload = req.options || {};

    if (req.fileUrl) {
      return this.http.submitUrl(model, req.fileUrl, payload, {
        pageRanges: req.pageRanges,
        batchId: req.batchId,
        signal,
      });
    }
    return this.http.submitFile(model, req.filePath!, payload, {
      pageRanges: req.pageRanges,
      batchId: req.batchId,

View on GitHub (pinned to 2661c7c0ef)