PaddlePaddle/PaddleOCR · error · InvalidRequestError

fileUrl and filePath are mutually exclusive.

Error message

fileUrl and filePath are mutually exclusive.

What it means

Raised as FileNotFoundError from submit_file in paddleocr/_api_client/_http.py:135 when the local file to upload does not exist (os.path.exists check). This is a plain builtin exception, not a PaddleOCRAPIError subclass — important when writing except clauses. It fires before any network activity, so it is purely a client-side path problem.

Source

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

      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,
      signal,
    });
  }

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Check the path: os.path.abspath(file_path) and confirm it exists in the environment that runs the code
2. Use absolute paths constructed from a known root (pathlib.Path(__file__).parent / 'file.pdf')
3. In Docker, verify the file is mounted/copied into the container
4. If the path comes from user input, validate existence early and surface a clear error

Example fix

# before
job_id = client.submit_file(model, "input/doc.pdf", {})
# after
from pathlib import Path
pdf = Path(__file__).parent / "input" / "doc.pdf"
if not pdf.is_file():
    raise SystemExit(f"Input file not found: {pdf}")
job_id = client.submit_file(model, str(pdf), {})

from pathlib import Path

def ensure_uploadable(path: str) -> str:
    p = Path(path).expanduser().resolve()
    if not p.is_file():
        raise FileNotFoundError(f"Upload file missing: {p}")
    return str(p)

try:
    job_id = client.submit_file(model, file_path, {})
except FileNotFoundError:
    # builtin exception, NOT a PaddleOCRAPIError — catch it separately
    logger.error("Input file not found: %s", file_path)
    raise

When it happens

Trigger: client.submit_file(..., file_path=...) where file_path points to a nonexistent path: typo, relative path resolved against the wrong working directory, file deleted, or wrong container mount.

Common situations: Relative paths in scripts run from a different cwd; Docker containers where the file is not mounted; tempfile already cleaned up; case-sensitive filesystem mismatches; path built with wrong variables.

Related errors

• Either file_url or file_path is required.
• file_url and file_path are mutually exclusive.
• Unsupported OCR model: {model}
• Unsupported document parsing model: {model}
• Unsupported model: {model}

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