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.

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)

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

• OCR result page is missing prunedResult.
• Document parsing result page is missing markdown.text.
• Model ${model} is not an OCR model.
• Unsafe resource filename: ${key}
• OCR result item is missing result.ocrResults.

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