File Names That Work on Windows and Break on the Server

Fine on the computer, broken online

A new page looks perfect on the designer's computer. Every photo appears and every PDF opens. Once it is uploaded, a few images show as empty boxes and one download leads to a not found page.

Nothing was deleted. The files are on the server, in the right folder, visible in the host's file manager.

The difference is the name. The page asks for Photo.JPG, the file is called photo.jpg, and the server treats those as two different files.

Windows does not, which is why nobody noticed before launch.

Why the two disagree

Windows ignores capital letters in file names. Ask it for PHOTO.jpg and it hands over photo.jpg without complaint. Macs behave the same way by default.

Most web hosting runs on Linux, which reads every letter exactly. On a Linux server, Photo.JPG, photo.JPG and photo.jpg can sit side by side as three separate files.

So a page tested with its files on the designer's computer passes every check. The mismatch appears only on the server.

The same happens when a site moves from a Windows host to a Linux one. Links that worked for years break overnight, all together.

Names that cause trouble

• Capital letters, especially cameras' uppercase .JPG endings.
• Spaces, which become %20 in a web address.
• Accented letters in French names and words.
• Symbols such as #, &, ? and apostrophes.
• Double extensions such as photo.jpg.jpg.

The last is the one Windows hides from its own users. Windows does not show file extensions unless someone changes a setting, so renaming a picture photo.jpg can quietly produce photo.jpg.jpg, and nobody can see why the link fails.

Spaces and symbols in addresses

Web addresses cannot contain spaces. A file called price list.pdf has to be requested as price%20list.pdf, and most browsers make the change quietly.

Not everything does. A link pasted into an email often breaks at the first space, and some programs swap the space for a plus sign, which the server does not read as a space.

Symbols are worse. A # tells the browser that what follows is a position within the page, so a link to invoice#42.pdf asks the server for a file called invoice and nothing more.

Ampersands, question marks and apostrophes cause similar trouble in other places. None is worth the risk in a file name.

Accents that look right and fail

Accented letters are a quieter problem, and a common one in Canada, where French names and words find their way into file names.

The same accented letter can be stored in more than one way, and a Mac, a Windows computer, an upload program and the server may each record it differently.

The name the page asks for then stops matching the name on disk, though the two look identical on screen. The file is visibly there, and still cannot be found.

A worked example

A small book publisher with a backlist of several dozen titles keeps a catalogue on its site, with a cover image and a one-page sell sheet for each book, used by bookstores and libraries.

Its designer rebuilt the catalogue on a Windows laptop, using files straight from the production folders: names like Cover FINAL.JPG, accented French words, and one sell sheet called Spring List #2.pdf.

The links were typed in whatever capitals came to mind, and on the laptop every cover appeared. Online, several were empty boxes, including every title with an accent, and the spring sell sheet would not open at all.

The designer renamed every file in lowercase, with hyphens for spaces and plain letters in place of accents, so each cover took the title's words joined by hyphens. The catalogue was updated to match.

Links already sent to bookstores in a newsletter were checked too, and the one pointing at an old name was redirected to the new file.

The publisher now names files before they leave production, which saves the designer the job entirely.

Finding the broken references already there

A site edited by several people over several years usually has some.

A link checker crawls the site the way a search engine does and lists every image, page and file that comes back as not found. Run it against the live site, not a copy on someone's computer.

Search Console's Crawl Errors report lists addresses Google could not find. On any single page, the browser's developer tools show each missing image as an error.

Server error logs, if your host provides them, show what visitors asked for and did not get.

Renaming without breaking more links

Renaming a file fixes one link and can break others. Before changing a name, find every page that uses it.

WordPress and similar systems store links inside page content, so a search within the system for the old name finds most of them. Theme files and stylesheets need checking separately.

Anything linked from outside the site, such as a PDF in an old newsletter or on a partner's page, should keep working through a redirect to the renamed file.

A naming rule for everyone

The lasting fix is one short rule that everyone who adds files follows.

Lowercase letters, numbers and hyphens only. No spaces, accents or symbols. A name that describes the content, such as spring-catalogue-2015.pdf or kitchen-island-walnut.jpg.

Put it in writing for staff, the designer and anyone who sends files for the site. Most of these problems begin with a file named on someone else's computer.

The counter-case

Some systems tidy names on upload. WordPress replaces spaces and removes several symbols from files added through its media library, so sites where everything goes through it see fewer of these problems.

It leaves capital letters alone, though, and files added by FTP, linked from theme files or written into hand-coded pages are not touched at all.

A site on a Windows server is also forgiving about capitals, until the day it moves.

Wherever files come from, name them in lowercase with hyphens, without accents or symbols, and check the live site after each upload.

The check

1. Run a link checker on the live site.
2. Read Crawl Errors in Search Console.
3. Turn on file extensions on office computers.
4. Rename files in lowercase with hyphens.
5. Update every page that links to them.
6. Redirect old names linked from elsewhere.
7. Write the naming rule down for everyone.

Step seven is what stops the problem returning, since broken names arrive with every new file named on somebody's own computer.

Windows can surprise an office in other ways too, as covered in the free Windows 10 upgrade on office computers.

Frequently asked questions

West Coast Media Solutions Inc. provides web design, web development, hosting, digital marketing, and business consulting to organisations across Canada, drawing on more than twenty-five years in the field.