crewAIInc/crewAI · error · ValueError

Error loading DOCX file: {e!s}

Error message

Error loading DOCX file: {e!s}

What it means

Raised by DOCXLoader._load_from_file() when opening or parsing the DOCX fails — e.g. python-docx raises PackageNotFoundError for a non-OOXML file, or the file is corrupt/encrypted. The broad except around DocxDocument(file_path) and the paragraph/table iteration re-raises as ValueError('Error loading DOCX file: ...') with the cause chained.

Source

Thrown at lib/crewai-tools/src/crewai_tools/rag/loaders/docx_loader.py:85

                    text_parts.append(paragraph.text)  # noqa: PERF401

            content = "\n".join(text_parts)

            metadata = {
                "format": "docx",
                "paragraphs": len(doc.paragraphs),
                "tables": len(doc.tables),
            }

            return LoaderResult(
                content=content,
                source=source_ref,
                metadata=metadata,
                doc_id=self.generate_doc_id(source_ref=source_ref, content=content),
            )

        except Exception as e:
            raise ValueError(f"Error loading DOCX file: {e!s}") from e

View on GitHub (pinned to 754d7323be)

Solutions

1. Validate the file is a real OOXML package: check the ZIP magic bytes (PK\x03\x04) and that word/document.xml exists inside.
2. Re-download or re-export the document; verify it opens in Word/LibreOffice.
3. If the document is password-protected, decrypt it (e.g. with msoffcrypto) to a new file before loading.
4. Delete and re-create partial temp files rather than retrying on the same bytes.

Example fix

# before
result = DOCXLoader().load(SourceContent('spec.docx'))  # actually old .doc renamed

# after
import zipfile
if not zipfile.is_zipfile('spec.docx') or 'word/document.xml' not in zipfile.ZipFile('spec.docx').namelist():
    raise ValueError('not a valid OOXML .docx — convert it first')
result = DOCXLoader().load(SourceContent('spec.docx'))

import zipfile\n\ndef is_valid_ooxml(path: str) -> bool:\n    try:\n        with zipfile.ZipFile(path) as z:\n            return 'word/document.xml' in z.namelist()\n    except zipfile.BadZipFile:\n        return False

try:\n    result = DOCXLoader().load(source)\nexcept ValueError as e:\n    if 'Error loading DOCX' in str(e):\n        quarantine_file(source.source)  # move aside, log, continue batch\n    else:\n        raise

When it happens

Trigger: Loading a file with a .docx extension that is actually the old binary .doc format, a .docx that is a renamed ZIP bomb or truncated download, an encrypted/password-protected document, or an HTML error page saved with a .docx suffix by the URL download path.

Common situations: Downloads interrupted leaving truncated files; users renaming .doc to .docx; Word documents saved with password protection; SharePoint/Google Docs export glitches producing non-standard packages; temp files partially written before the process died.

Related errors

• Unable to extract content from documentation site: {docs_url
• python-docx is required for DOCX loading. Install with: 'uv
• Source must be a valid file path or URL, got: {source_conten
• Error fetching content from URL {url}: {e!s}
• Failed to extract completion: {json.dumps(debug_info, indent

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/c7e1a1b5b1e41388. Report an issue: GitHub.