Fixing the “Filename Contains Spaces” EPUB Error

The error: Filename contains spaces. Consider changing filename such that URI escaping is not necessary.

Why This Happens

This error isn’t about your EPUB file itself — it’s about the underlying HTML source file. Spaces in a filename need to be “escaped” (converted into URL-safe characters) to work reliably across all reading systems, and EPUB validators flag this as a potential compatibility issue.

The Fix

Give your HTML file a name with no spaces (use hyphens or underscores instead — e.g.,my-book-chapter1.html rather than my book chapter1.html).

⚠️ Don’t Just Rename the File

This is the part that trips people up: don’t simply rename the existing HTML file to remove the spaces. Every image reference inside that file points to a specific file path tied to the original name — renaming it after the fact breaks those references, and your images will point to the wrong location.

Instead: delete the HTML file and recreate it from scratch with the correct, space-free name from the start. It takes a similar amount of effort but avoids a much harder-to-diagnose problem afterward — broken image links that don’t show an obvious error message.