Troubleshooting

Find the message you're seeing, what it means, and how to fix it.

Setup errors

Message	Cause	Fix
`pandoc is required but was not found on your PATH`	pandoc isn't installed, or your shell can't find it.	Install pandoc, then open a new terminal.
`pandoc 3.6 or newer is required`	Your pandoc is too old, which is common with Linux packages.	Install a newer version.
`this pandoc build does not allow memory limits`	Your pandoc build turned off the option word2html uses to limit memory.	Use an official build.

Input errors (exit 1)

Message	Cause	Fix
`File not found: …`	The path is wrong.	Check the spelling and your current folder.
`Expected a .docx file, got: …`	The file doesn't end in `.docx`.	Save it as `.docx` in Word. Just renaming a `.doc` won't work.
`Not a regular file: …`	The path is a folder or something else that isn't a file.	Point it at the document itself.
`File is empty: …`	The file has no content, often from a failed download or sync.	Get a fresh copy.
`This is a password-protected or legacy .doc file, not a .docx`	The document is encrypted, or it's an old-format file named `.docx`.	Remove the password, or re-save it as `.docx` in Word.
`Not a valid .docx file (it is not a readable zip archive)`	The file is corrupt, incomplete, or not really a Word document.	Open it in Word and save a new copy.
`not a Word document: …`	It's a zip file, but required parts are missing.	Open it in Word and save a new copy, if it opens.
`… is not well-formed XML`	Part of the document is damaged, or was written by a faulty tool.	Open it in Word and save a new copy.
`… contains a DOCTYPE, which Word documents never use`	The document was crafted or written by unusual software.	Don't trust it. Re-save it in Word if you know where it came from.
`archive member has an unsafe path`, `archive member is encrypted`, `archive has more than one member named …`	The archive's structure is unusual, and is likely crafted or damaged.	Don't trust it. Re-save it in Word if you know where it came from.
`pandoc could not read this document`	The file passed the checks, but pandoc couldn't process it.	Open it in Word and save a new copy.

Limit errors (exit 1)

Message	Fix
`File is … over the … limit`	Use `--max-file-size` if you trust the file.
`pandoc exceeded its …-byte memory limit`	Use `--max-memory` if you trust the file. See how much memory you need.
`pandoc did not finish within … seconds`	Use `--timeout` if you trust the file.
`… is nested more than 256 levels deep`	This is very unusual in a real document. Don't trust it unless you know where it came from. From Python, you can raise `max_xml_depth`.
`… is larger than the 64 MiB limit for one part`, `document expands to …`, `archive has … entries`	The document is unusually large or crafted. From Python, you can raise these limits.

Refusals (exit 3)

Message	Fix
`refused: unsafe link: …`	Remove or correct the link in Word. Without `--strict`, it converts with a warning.
`refused: … hidden in Word …`	Remove the hidden text. Without `--strict`, it converts with a warning and publishes the text.
`refused: active content: …`	There's no option to allow this. Don't trust the document unless you know where it came from. Re-saving a known document in Word may clear it.

Output errors (exit 1)

Message	Fix
`Output path is a directory: …`	A folder has the name word2html wants to use. Rename the folder or the document.
`Could not write …`	Check that you have write permission for the folder and there's free disk space. word2html writes next to the input, so a read-only input folder won't work.

Common questions

An image is missing from the HTML: It's probably linked rather than embedded, which word2html warns about: image(s) are not stored in the document. In Word, insert the picture normally, without "Link to File".
The page doesn't look like my Word document: word2html keeps structure and content, not visual design. The output uses pandoc's default CSS, which you can override in your own stylesheet.
I got a hidden-text warning, but I can't see any hidden text: Turn on hidden text display in Word, using the ¶ button on the Home tab. If the warning seems wrong, please open an issue, without attaching anything confidential.
Why did my previous .html file disappear?: word2html replaces an existing output file on success. Keep hand-edited copies under a different name.
The output is much bigger than the .docx: Images are embedded using base64, which adds about a third to their size, and they're stored in the HTML rather than compressed in a zip archive.