Anvil Tools
A designer finishes an image, saves it to a shared folder, and sends the filename to a developer.
The developer tries to use it on the website.
The image does not load.
The file itself is valid, its dimensions are correct, and the browser supports the format. Yet the server cannot find the requested resource.
The problem may be something much smaller than the image: its filename.
Operating systems and web servers do not always interpret filenames in exactly the same way. A name that works on one computer may contain characters another system rejects, collide with an existing filename, or fail because of differences in capitalization.
These problems affect more than developers. They occur when sharing photographs, preparing PDF submissions, organizing projects, synchronizing folders, and uploading documents.
The solution is not to remove every unusual character from every file. It is to understand which rules belong to the destination and choose names that are readable, predictable, and compatible with the intended workflow.
A filename is not just a label
Consider a product photograph named Blue Ceramic Cup.png.
A person sees a descriptive label.
The operating system sees a sequence of characters used to identify a file within a directory.
A website may see a resource path used to locate that file.
An upload service may treat the submitted name as untrusted information that needs validation.
These interpretations overlap, but they have different requirements.
For example, spaces can be perfectly acceptable in local filenames.
However, spaces inside web URLs require appropriate URL handling. A website may therefore choose a simpler path such as blue-ceramic-cup.png.
The important distinction is that a valid local filename is not automatically a well-designed web filename.
Likewise, a filename that a content-management system accepts may still need adjustment before it is used in an automated workflow.
The three environments that matter most
Windows, macOS, and Linux commonly use different filesystem configurations and filename-handling rules.
The exact behavior also depends on the filesystem, application, and settings.
| Environment | Important consideration |
|---|---|
| Windows | Reserved characters and device names; commonly case-insensitive filename handling |
| macOS | Commonly uses case-insensitive APFS, but case-sensitive configurations are available |
| Linux | Common Linux filesystems generally distinguish uppercase and lowercase filenames |
| Websites | URL paths and deployed asset names must match the server's actual routing behavior |
| Upload platforms | Additional restrictions may apply regardless of the operating system |
A filename does not become universally valid merely because it was created successfully on one computer.
For shared workflows, compatibility should be assessed against every destination where the file must be opened, uploaded, renamed, or retrieved.
Why certain characters fail on Windows
Microsoft documents several characters that are reserved in ordinary Windows filenames.
These include the less-than and greater-than signs, colon, double quotation mark, forward slash, backslash, vertical bar, question mark, and asterisk.
A document title such as:
Monthly Report: October/2026?
may be understandable to a person.
But turning that title directly into a Windows filename introduces several invalid characters.
A more portable alternative would be:
monthly-report-october-2026.pdf
The new name uses ordinary letters, numbers, hyphens, and a conventional extension.
This does not mean punctuation is forbidden in every filename on every operating system.
It means the selected punctuation avoids common Windows filename restrictions and is easier to reuse across systems.
Windows also reserves certain names
There is a less obvious restriction.
Windows treats names such as CON, PRN, AUX, and NUL as reserved device names in normal file operations.
Names such as COM1 and LPT1 also have special restrictions.
Adding an extension does not automatically make these names safe.
For example, CON.txt is not an ordinary portable filename for Windows.
This matters when generating filenames automatically from user input.
Imagine a form that creates a document using a customer's chosen project name.
If the customer enters CON, simply appending .pdf may still produce a name that fails.
A reliable application should validate its generated filenames against the requirements of the destination filesystem.
Human-readable case conversion alone does not perform that validation.
Why capitalization can break a working project
Consider these two image references:
| Reference | Filename |
|---|---|
| Original | Product-Photo.png |
| Revised | product-photo.png |
The names contain the same letters apart from capitalization.
On a commonly configured Windows filesystem, they may refer to the same file.
On a case-sensitive filesystem, they are different names.
This becomes important when a website is developed on one operating system and deployed to a server with different case-handling behavior.
A local preview might successfully load a file even when the capitalization in the code differs from the capitalization of the actual filename.
After deployment, the website may request a resource that the server does not recognize as the same path.
The result can be a missing image or another file-not-found error.
The relevant principle is:
Use one exact spelling for both the stored filename and every reference to it.
Do not rely on an operating system correcting capitalization differences for you.
For new projects, consistent lowercase names can reduce this category of mistakes.
However, changing the case of an existing filename requires reviewing everything that references it.
macOS is not universally case-insensitive
Apple's APFS filesystem supports both case-sensitive and case-insensitive configurations.
Case-insensitive behavior is common on macOS, but it is not guaranteed for every disk or installation.
This means an application should not assume that Photo.png and photo.png will always identify the same file on every Mac.
A project may also move from a Mac to a Linux server, external drive, repository, or network storage system with different rules.
A portable naming policy should therefore treat capitalization consistently rather than relying on the behavior of the current computer.
This is particularly valuable for web assets, automation scripts, and shared development projects.
Why spaces are valid but sometimes inconvenient
A filename such as Annual Report 2026.pdf is common and readable.
For ordinary document sharing, spaces are not automatically a problem.
However, they introduce another consideration when filenames become part of web URLs or command-line operations.
For example, spaces in URLs require appropriate encoding.
In command-line environments, filenames containing spaces may need quotation or escaping, depending on the command and shell.
That does not make spaces inherently unsafe.
It means the surrounding application must handle them correctly.
For a workflow involving many automated scripts, downloaded assets, or web paths, a name such as annual-report-2026.pdf can be easier to work with.
For a document intended mainly for people opening files in a graphical interface, a readable name containing spaces may be entirely reasonable.
The destination should determine the convention.
Why Google recommends hyphens in readable URLs
Filename conventions and URL conventions are related but not identical.
For website paths, Google Search Central recommends using hyphens to separate words.
Consider these three paths:
| URL path | Readability |
|---|---|
/annual-report-2026 | Words are clearly separated |
/annual_report_2026 | Readable, but not Google's preferred separator style |
/annualreport2026 | Word boundaries are less obvious |
Google's guidance recommends hyphens rather than underscores for separating words in URLs.
This does not mean every existing underscore-containing URL must be changed.
It also does not mean renaming a file guarantees better search rankings.
A URL's content, accessibility, canonical handling, and the site's overall quality matter too.
The practical lesson is narrower:
When choosing new, readable website paths, lowercase words separated by hyphens are often a sensible convention.
For an existing indexed URL, changing its path can have consequences.
The old URL may need an appropriate permanent redirect, and internal links, canonical references, and sitemap entries may need updating.
A cleaner name is not automatically worth breaking an established link.
The extension deserves its own treatment
A filename commonly contains a base name and an extension.
For example:
| Part | Value |
|---|---|
| Base name | product-photo |
| Extension | .png |
| Complete filename | product-photo.png |
The base name describes or identifies the content.
The extension helps software determine how the file should be handled.
When preparing a new name, keep those responsibilities separate.
For example, changing Product Photo.PNG to product-photo.png is a filename and capitalization change.
But changing product-photo.jpg to product-photo.png does not actually convert JPEG image data into PNG.
A proper format conversion requires software that reads the source format and writes the destination format.
Renaming alone does not create transparency, increase resolution, remove metadata, or change how the underlying image is encoded.
If the format must change, use an appropriate converter.
Then inspect the exported file.
What goes wrong when a case converter receives the extension
Suppose you want to convert the phrase:
Quarterly Product Report
into a lowercase, hyphen-separated name.
The desired base name might be:
quarterly-product-report
You then append the correct extension:
quarterly-product-report.pdf
This is safer than feeding Quarterly Product Report.pdf into a general-purpose identifier converter and assuming the extension will remain intact.
Identifier-style transformations may treat punctuation as a word separator.
The dot before an extension could be removed or replaced.
A converter might produce a name-shaped string rather than a usable filename with the intended extension.
Convert the descriptive base name first. Preserve or append the verified extension separately.
This avoids confusing case conversion with file-format handling.
A filename can be valid but still cause a duplicate
Imagine a team preparing images for an online catalog.
Two contributors export separate photographs using the name product-final.png.
Each file is valid.
But when the files are copied into one directory, the names collide.
Depending on the application, the second copy might be renamed, rejected, or offered as a replacement for the first.
This is not a character-validity problem.
It is an identity problem.
If several files describe different items, their names need enough distinguishing information.
A simple approach is to include a stable product or project identifier.
For example:
| Purpose | Suggested name |
|---|---|
| Product photograph | cup-104-front.png |
| Alternate angle | cup-104-side.png |
| Reviewed catalog image | cup-104-catalog-v02.png |
| Supporting PDF | cup-104-specification.pdf |
These names are examples of an internal convention, not a standard required by a particular marketplace.
They are descriptive without relying on vague labels such as final-final-new.
For systems that must guarantee uniqueness, descriptive filenames alone are insufficient.
The application should enforce an appropriate uniqueness or naming policy.
Why dates and version numbers help
A shared project can accumulate several legitimate versions of the same document.
Consider:
proposal.pdf
proposal-new.pdf
proposal-final.pdf
proposal-final-2.pdf
After several revisions, the names no longer provide a dependable history.
A more structured convention can include a date or revision identifier.
For example:
project-proposal-2026-10-09-v02.pdf
Using a consistent year-month-day date format helps dates sort chronologically when the names are otherwise comparable.
A revision indicator such as v02 can help distinguish versions prepared on the same day.
But the filename should not become a substitute for proper document version control.
A filename alone does not prove which version was approved, who edited it, or whether it is the authoritative copy.
For important projects, maintain an approval or revision record separately.
Unicode filenames are legitimate, but portability still matters
Modern operating systems support filenames containing many languages and writing systems.
A photograph can legitimately have a name containing accented letters, Arabic, Urdu, Hindi, Chinese, or other Unicode text.
These characters should not be described as inherently invalid or insecure.
However, moving filenames between older software, restrictive upload platforms, scripts, and differently configured filesystems can create compatibility challenges.
Unicode also allows visually similar text to have different underlying character representations.
Some filesystem implementations account for certain normalization differences, while others handle comparisons differently.
For ordinary users, the key is not to memorize Unicode normalization algorithms.
It is to avoid assuming that visual similarity guarantees identical filenames across every system.
If a project must work with a restrictive destination, test representative names before committing to a naming convention.
For public-facing assets where a simple ASCII filename is acceptable, that may be the most portable option.
For documents where the original language is important, preserving the correct written name may be the better choice.
Compatibility should not come at the cost of silently changing a person's name or a document's meaning.
Filenames and upload security are separate responsibilities
A file named safe-document.pdf is not guaranteed to be a safe PDF.
The name does not establish that the file's contents match the extension.
It does not prove that the file is harmless, that the uploader is authorized, or that storing the file is appropriate.
Applications accepting uploaded files need controls beyond filename normalization.
OWASP's File Upload Cheat Sheet recommends measures such as validating allowed file types, restricting filenames and file sizes, handling storage locations safely, and applying suitable security checks.
An upload system may also generate its own internal storage name instead of trusting the submitted filename.
This is an important distinction.
A naming convention improves organization and compatibility. It is not a file-security validation system.
People preparing files can choose sensible names.
The receiving application must still enforce its own security requirements.
A practical filename policy for a small team
Suppose a team regularly exchanges PDF documents, product photographs, and website images.
A reasonable shared policy could be:
| Element | Working rule |
|---|---|
| Letters | Use lowercase for shared web assets |
| Word separator | Use hyphens for new public-facing paths |
| Numbers | Use when they add useful identity |
| Dates | Use consistent YYYY-MM-DD ordering |
| Versions | Use v01, v02, and similar labels where needed |
| Extension | Preserve the verified file format |
| Reserved characters | Avoid characters prohibited by the destination |
| Reserved names | Check operating-system restrictions |
| Length | Keep names reasonably short and within destination limits |
This is an example team policy.
It is not a claim that every operating system requires lowercase filenames or hyphens.
For a private document library, a different convention may be equally appropriate.
The value of a naming policy is that contributors can predict how files should be named before they exchange them.
That reduces last-minute fixes and inconsistent asset references.
Using Anvil Tools Text Case Converter
The Anvil Tools Text Case Converter can help prepare a consistent base name.
It supports transformations including lowercase, uppercase, title case, sentence case, camelCase, PascalCase, snake_case, and kebab-case.
For example, start with the descriptive phrase:
Customer Order Summary
Choose kebab-case to prepare a lowercase, hyphen-separated identifier:
customer-order-summary
If you are preparing a PDF filename, preserve the actual extension and form:
customer-order-summary.pdf
For a website image, the same naming approach could produce:
customer-order-summary.png
The converter handles text transformations locally in the browser.
It is not a complete filename validation tool.
It does not verify Windows reserved device names, guarantee uniqueness across a shared directory, inspect a file's actual type, or rename files on your computer.
Its identifier modes also normalize text and remove punctuation, so the output should be reviewed before being used as a final filename.
For users preparing ordinary headings rather than filenames, see Title Case vs Sentence Case: Editing Headlines, Labels, and Text Without Losing Meaning.
Editorial capitalization and technical filename conventions are related, but they answer different questions.
A final check before sharing or publishing
Consider a file named New Product Photo.PNG.
Before publishing it to a website, answer these questions:
Does the name identify the right asset?
A descriptive name is easier to maintain than IMG_2048.PNG.
Is the capitalization consistent?
A lowercase convention can reduce problems when assets move between environments.
Will the extension still reflect the actual file type?
Renaming an extension is not a format conversion.
Does the destination accept the name?
Check any restrictions imposed by the filesystem, uploader, or publishing platform.
Could the name collide with another file?
Add an appropriate identifier if multiple files might otherwise share the same name.
Are existing references affected?
If the image is already used on a website, changing its filename can break links unless the references and routing are updated correctly.
If all these checks pass, new-product-photo.png may be a sensible name for the asset.
But the correct choice still depends on its destination and role.
The real goal is predictable behavior
A filename may look like a minor detail, but it crosses several boundaries.
It moves between operating systems, filesystems, applications, upload services, and websites.
Each boundary can introduce different rules.
The most dependable approach is to choose descriptive names, use a consistent convention, preserve correct extensions, and verify compatibility with the systems that will actually handle the files.
For new public website assets, lowercase words separated by hyphens are often a convenient starting point.
For established files, avoid renaming without checking references and dependencies.
And for uploaded content, remember that a well-formed name does not replace security validation.
A good filename is not simply one that looks neat. It is one that identifies the correct file and continues to work wherever that file needs to go.
Try the relevant text tool
Preparing filenames, URL-friendly phrases, or consistent labels for a project?
Use the Anvil Tools Text Case Converter to turn descriptive text into formats such as kebab-case or snake_case.
Review the result, preserve the correct file extension, and apply the destination's naming requirements before saving or uploading the actual file.