Troubleshooting

ImportError: ... is required. Install: pip install ...

Every optional-dependency loader raises a clear, actionable ImportError naming the exact package to install. This is by design — see Installation → Optional dependencies by format for the full mapping of loader → dependency.

try:
    docs = PDFLoader("file.pdf").load()
except RuntimeError as e:
    # PDFLoader raises RuntimeError (not ImportError) only when ALL backends fail
    print(e)

Note the distinction: PDFLoader raises RuntimeError (not ImportError) when every backend fails, because it tries multiple backends and only gives up after all of them are exhausted. Single-backend loaders (DocxLoader, HTMLLoader, ExcelLoader, etc.) raise a direct ImportError immediately.

FileNotFoundError / ValueError at construction, not at load()

BaseFileLoader.__init__ validates the file eagerly (_validate_file()), so these errors surface as soon as you construct the loader:

loader = TextLoader("missing.txt")  # raises FileNotFoundError HERE
docs = loader.load()                 # never reached

If you're catching exceptions only around .load() calls, wrap the constructor too, or catch around both together.

ValueError: Unsupported extension '...' for file ...

Raised by BaseFileLoader._validate_file() when a loader's SUPPORTED_EXTENSIONS doesn't include the file's suffix, or by AutoLoader/GraphLoader/TableLoader when their own dispatch tables don't recognize the extension. Check the loader's SUPPORTED_EXTENSIONS class attribute or the relevant page in API Reference for the exact list.

RuntimeError: All PDF backends failed for ...

Every one of PyMuPDF, pdfplumber, and pypdf either isn't installed or failed to parse the file. Install at least one:

pip install pymupdf

If a backend is installed but still fails, the error message includes Last error: ... with the underlying exception — this could indicate a genuinely corrupted PDF, not just a missing dependency.

ValueError: PDF is password-protected. Provide 'password' in config.

PDFLoader("file.pdf", password="the_password").load()

If you already provided a password and still see "Wrong password for PDF.", double check the password itself — this message specifically means authentication was attempted and rejected.

.doc files raising ImportError even though python-docx is installed

python-docx cannot read the legacy binary .doc format at all — it's designed for .docx only. DocxLoader needs either LibreOffice (a libreoffice/soffice binary on PATH) or the textract package for .doc support. See DocxLoader for the exact fallback chain.

UnicodeDecodeError from CSVLoader

This only surfaces if both the configured encoding and latin-1 fail — which is unusual, since latin-1 can decode any byte sequence. If you see this, double-check the file isn't corrupted or truncated mid-multi-byte-sequence in a way that breaks even the fallback path, or that you're not accidentally pointing the loader at a binary (non-text) file.

Garbled/mojibake text output (not an exception)

If output text contains unexpected characters (e.g. é instead of é, or unreadable Arabic), the loader likely fell through to the latin-1 fallback without correctly detecting the true encoding. Fixes:

1. Install chardet: pip install chardet.
2. Explicitly pass the correct encoding if you know it: TextLoader(path, encoding="windows-1256").
3. Check doc.metadata["encoding_used"] (available on TextLoader/MarkdownLoader output) to see what was actually used.

openpyxl/xlrd errors on .xls files

.xlsx/.xlsm need openpyxl; the legacy .xls binary format needs pandas and xlrd — openpyxl alone cannot read .xls. See Installation.

Excel ValueError: Sheet '...' not found. Available: [...]

The message itself lists valid sheet names — use load_all_sheets=True if you want every sheet, or correct the sheet_name value.

Tesseract OCR errors (pytesseract.TesseractNotFoundError or similar)

pip install pytesseract pillow only installs the Python wrapper — you also need the actual Tesseract OCR binary installed system-wide (see the Tesseract install guide). For Arabic OCR specifically, also install the Arabic language data package (e.g. sudo apt install tesseract-ocr-ara on Debian/Ubuntu) — without it, lang="ara+eng" will fail even with Tesseract itself correctly installed.

ImageOCRLoader/PDFMultimodalLoader return no text / empty list

Check:

• Is the image actually legible at a reasonable resolution? Very low-DPI scans often defeat OCR entirely.
• Try preprocessing=False — the fixed grayscale+threshold preprocessing can sometimes hurt more than help on images with uneven lighting.
• Try a different psm value — 6 for a single uniform text block, 11 for sparse/scattered text.
• For PDFMultimodalLoader, confirm min_image_size isn't filtering out the images you care about (default floor is ≈70×70px).

GraphLoader/TableLoader config overrides not taking effect

Both classes have keyword-only constructor arguments that always overwrite the corresponding fields on a passed-in config= object:

• GraphLoader(path, config=my_config, include_nodes=False, include_edges=True) — the include_nodes/include_edges values here always win, even over my_config.include_nodes.
• TableLoader(path, config=my_config, output_format="json", per_row=True) — same pattern for output_format/per_row.

If you set these fields inside config= but not also as direct kwargs, they'll be silently reset to the constructor defaults (True/True for GraphLoader, "markdown"/False for TableLoader). See the warnings on the Graph and Table API pages.

DirectoryLoader raises on the first bad file instead of continuing

Default silent_errors=False means any single file's load failure aborts the whole directory. Set silent_errors=True to log and skip failing files instead:

DirectoryLoader("./corpus/", silent_errors=True).load()

DirectoryLoader output seems to only contain some file types

Check that the extensions you expect are actually in EXTENSION_MAP (document_loaders.config_loader.EXTENSION_MAP) — unsupported extensions are silently filtered out during file collection, with no warning logged. If you need custom extensions supported, see Advanced Usage → Wiring a custom loader into directory scanning.

ConnectionError: Failed to fetch ... after N attempts

WebLoader exhausted config.max_retries (default 3) with exponential backoff. Increase max_retries/retry_delay, check the target URL is actually reachable, or inspect whether the site is blocking the default User-Agent (customize via headers).

MultiURLLoader seems slower than expected despite high max_workers

The global delay_between_requests semaphore enforces a floor on how fast new requests can start, regardless of worker count — raising max_workers alone won't bypass this. Lower delay_between_requests if the target site's rate limits allow it.

Related pages

• FAQ
• Installation
• Security