Alt text is a raw filename

What is this issue?

An <img> element has a non-empty alt attribute, so it isn’t caught by a simple missing-alt check, but the attribute’s value is a raw filename rather than a meaningful description: a camera-generated string like DSC08234.JPG, a CMS-generated upload name like hero-banner-final-v2.png, or a slightly more readable but still non-descriptive name like team-photo.jpg with no actual content description attached.

This most often happens automatically: a content management system defaults the alt field to the uploaded file’s name when nobody enters a real description, and the image publishes with that default intact. The image has an alt attribute (enough to pass a check for its mere presence), but not a useful one.

Why does this matter?

A screen reader reads alt text exactly as written, character by character where needed: a filename like IMG_4821.jpg is announced as something close to “IMG underscore 4821 dot jpg,” which tells a listener a file exists with that name and nothing else. For a product photo, a chart, a team photo, or any image conveying real information, that’s a complete loss of content a sighted user gets instantly just by looking.

This tends to happen at scale rather than as an isolated incident, since it’s usually caused by a CMS default rather than a one-off mistake; a single unfixed upload flow can produce dozens or hundreds of filename-labeled images across a site, each one silently unusable for a screen reader user browsing image-heavy content like a product catalog or a photo gallery.

Who is affected?

• Screen reader users: hear a literal filename read character by character in place of any actual description of the image, providing zero information about its content or purpose.
• Cognitive disabilities: users relying on alt text summaries to quickly understand page content without processing the full visual layout get a meaningless string instead of the intended shortcut.

What users experience

Marcus uses JAWS on his Windows laptop to browse an online furniture store’s product gallery. He tabs through a product page’s thumbnail images, and JAWS announces “graphic, DSC08234 dot jpg,” then “graphic, DSC08235 dot jpg,” then “graphic, DSC08236 dot jpg” for three different angles of the same armchair, each filename technically unique but none of them describing color, fabric, or angle. He has no way to tell whether he’s looking at the front, side, or a close-up of the fabric texture without opening each image individually and asking someone sighted to describe it.

How do I fix it?

Replace the filename with a short, accurate description of what the image shows or communicates. This works because it addresses the actual purpose of the alt attribute directly (conveying the same information the image gives a sighted viewer) rather than leaving a value that happens to satisfy an attribute-presence check without doing that job.

Describe the image’s content or function, not its filename or file format: “Team standing outside the new office entrance,” not “team-photo-2024.jpg.” For product images specifically, include the details a shopper would actually need: color, angle, or distinguishing feature, especially when multiple images of the same product only differ by exactly those details.

Code Examples

<img src="/uploads/IMG_4821.jpg" alt="IMG_4821.jpg">

<img src="/uploads/IMG_4821.jpg" alt="Team standing outside the new office entrance">

The src attribute (where the actual file lives) is completely unaffected by this fix; only the alt text changes, from a meaningless filename to a description that tells a screen reader user what the photo actually shows, the same information a sighted visitor gets by looking at it.

Common Mistakes

Mistake: “The image has alt text, so it’s already accessible.” Presence alone isn’t the bar; the text has to actually describe the image. A filename technically satisfies “alt text exists” while providing none of the information that attribute is meant to convey, which is exactly why this rule exists as a distinct, subtler check from a simple missing-alt-attribute rule.

Mistake: “This is just an upload-flow bug, not something worth fixing content by content.” Both are true, and both need addressing. Fix the individual images your users are seeing right now, and separately check whether your CMS’s upload flow is defaulting alt to the filename; otherwise every future upload repeats the same failure indefinitely.

Mistake: “A slightly cleaned-up filename, like ‘blue-armchair-front.jpg’, is good enough since it’s more readable than a camera string.” It’s a smaller failure but still a failure if that string is literally what’s read aloud; a screen reader doesn’t parse hyphens into spaces or strip the extension for you; “blue dash armchair dash front dot jpg” is still not the same as a real sentence describing the chair.

How RedFlag Detects This

AI-assisted: flagged by the optional Review Labels feature. RedFlag’s label-review workflow surfaces images whose alt text matches a filename-like pattern (a bare uploaded-file-style string, often with a recognizable image file extension), and a human reviewer confirms whether the flagged text is genuinely a leftover filename before it’s recorded as a violation. This is a hybrid flag-then-confirm process, not a deterministic rule that runs unattended on every scan.

False negative: a filename that’s been lightly edited to look more like a description (removing the extension, adding spaces) can slip past the pattern match that originally surfaced the candidate, even though it’s still not a real description of the image’s content. False positive: a genuinely intentional alt text that happens to resemble a filename pattern, such as an image whose real subject is a screenshot of a file listing, can be surfaced for review even though the text is accurate in that specific context. Manual step: the reviewer’s confirmation that the flagged text really is a filename standing in for a description, rather than a coincidentally filename-shaped but accurate description, is the actual detection step.

Manual Testing

1. Open the page in Chrome or Firefox with NVDA or VoiceOver running, or inspect alt attributes directly in DevTools.
2. Tab to or inspect every meaningful (non-decorative) image on the page.
3. Read the announced or inspected alt text and check whether it looks like a filename: a string ending in .jpg, .png, .gif, .svg, or similar, or containing camera-generated patterns like IMG_ or DSC.
4. For any filename-like alt text, confirm the image actually needs a real description (rather than being decorative, which should use alt="" instead) and rewrite it accordingly.

Related WCAG Success Criteria

1.1.1 Non-text Content: All non-text content must have a text alternative that serves the equivalent purpose. A filename-as-alt-text technically populates the attribute while providing none of the equivalent information the criterion requires, which is exactly the gap this rule targets.

Related Issues

Image is missing alt text is the more severe, automated sibling check: no alt attribute at all rather than one present but meaningless.

Alt text is a filename or placeholder word is RedFlag’s automated pattern-matching cousin of this rule, catching a related but distinct set of generic filler words and filename patterns through a deterministic regex rather than AI-assisted human review.

Image input is missing alt text covers the equivalent naming failure for <input type="image"> elements specifically, where a missing or filename-based alt breaks both the image’s description and the input’s accessible name at once.

Alt text repeats adjacent visible text is a different alt-text quality problem reviewed through the same AI-assisted label-review workflow: text that’s redundant rather than meaningless.

Image map area element is missing alt text extends the same non-text-content naming requirement to clickable regions inside an image map.

References

• W3C Understanding 1.1.1: Non-text Content
• W3C Technique H37: Using alt attributes on img elements
• WebAIM: Alternative Text