You load a page expecting an image, and you get alt text instead. Or the broken image icon. Either way, the browser is telling you it couldn’t fetch or render the file behind the src URL.
This usually comes down to paths, naming, server headers, or browser security rules. We’ll run through the common causes, show a quick DevTools workflow to pinpoint the failure, then call out where manual image handling starts to cost real time. Finally, we’ll show how Cloudinary avoids most of these issues with consistent, URL-based delivery.
Key takeaways:
- When an HTML image can’t load, the browser shows the alt text instead to keep the page understandable. This can happen due to broken URLs, unsupported formats, server errors, or network issues, and fixing it ensures better layout, performance, and user experience.
- If images aren’t loading and alt text appears, check the URL, file permissions, format support, and network response for errors like 404 or 403. Also review MIME types, HTTPS use, image size, caching rules, and alt text to ensure reliable and accessible image delivery.
In this article:
- Why Your HTML Shows Alt Text Instead of the Image
- A Checklist to Ensure Images Display Correctly
- Path and URL Errors: Relative vs. Absolute Paths
- Case Sensitivity and File Naming Issues
- Server-Side Issues: Permissions, MIME Types, CORS
- Browser Issues: Cache and Mixed Content
- Writing Effective Alt Text and Fallbacks
- Debugging with Browser DevTools
- How Cloudinary Simplifies Image Delivery
Why Your HTML Shows Alt Text Instead of the Image
When an HTML image fails to load, the browser displays the image’s alt text in its place. This is expected behavior and helps users understand what the image showed. Several issues can cause this to happen, even when the image tag itself looks correct.
A common reason is an incorrect file path or URL. If the image file was moved, renamed, or never uploaded, the browser cannot retrieve it. Unsupported formats or corrupted files can also prevent images from rendering properly.
Server side issues such as permission errors, blocked requests, or missing headers may stop the image from loading. Network problems and slow connections can cause timeouts, especially with large files.
When images fail, alt text becomes visible to maintain accessibility and provide context—as long as you provide it. While this protects usability, it also signals a problem that can affect layout, performance, and user trust. Identifying the cause helps ensure images load reliably and display as intended across devices.
A Checklist to Ensure Images Display Correctly
If images are not loading and alt text appears instead, a systematic check can help you find the issue quickly. This checklist covers the most common areas that affect image delivery and rendering on a webpage.
- Verify the image URL: Make sure the file path is correct and points to an existing image. Check for typos, missing folders, or renamed files.
- Confirm file accessibility: Ensure the server allows public access to the image and permissions are set correctly.
- Check supported formats: Use widely supported formats like JPG, PNG, or WebP to avoid browser compatibility issues.
- Inspect network requests: Use browser developer tools to see if the image request returns errors like 404 or 403.
- Review MIME types: Confirm the server sends the correct content type for image files.
- Test HTTPS consistency: Mixed content can block images when a page loads over HTTPS.
- Validate image size: Very large images may fail to load on slow connections or time out.
- Add meaningful alt text: Alt text helps accessibility and provides context when images fail.
- Check caching rules: Incorrect cache headers can cause outdated or broken image references.
- Use responsive delivery: Serving images optimized for different devices improves reliability.
Path and URL Errors: Relative vs. Absolute Paths
Path mistakes are the top reason images don’t display in HTML. They’re also easy to miss because the same code can behave differently across environments.
Relative paths resolve from the current document’s location. Move the HTML file (or change routing), and the path can silently break. Absolute paths starting with / resolve from the domain root, which is usually more stable but still tied to your deployment layout.
<!-- Relative path --> <img src="images/hero.jpg" alt="Hero banner"> <!-- Absolute path --> <img src="/assets/images/hero.jpg" alt="Hero banner"> <!-- Full URL --> <img src="https://example.com/assets/images/hero.jpg" alt="Hero banner">
Local setups add another wrinkle. What works on localhost:3000 might fail after you deploy because your build output and public asset paths aren’t the same, especially once they’re behind CDNs or other parts of your tech stack.
Case Sensitivity and File Naming Issues
If it works on your local machine and breaks in production, check the casing. Many macOS and Windows setups are case-insensitive by default. Most Linux servers are not. Logo.PNG and logo.png are different files.
File extensions matter too. If someone renamed a JPEG to .png, some browsers will still display it, and others won’t. That’s not something you want to debug across devices.
The practical baseline: lowercase filenames, no spaces, and extensions that match the actual format. Enforcing that across a large repo is where the friction starts.
Server-Side Issues: Permissions, MIME Types, CORS
Sometimes the file exists and the path is correct, but the server response makes the browser reject it.
- Permissions: If the server user can’t read the file, you’ll see a 403. This can happen after migrations or manual uploads.
- MIME types: Servers should return the right
Content-Type. Misconfigured types can cause inconsistent handling, especially for newer formats. - CORS: If the image is loaded from another domain, the browser may enforce cross-origin rules depending on how it’s used (and how the server responds).
A CORS error often looks like this:
Access to image at 'https://cdn.example.com/image.jpg' from origin 'https://example.com' has been blocked by CORS policy
Fixing these usually means server access and config changes. That’s fine for a single site. It’s not fun when you have multiple environments and multiple teams touching the same assets.
Browser Issues: Cache and Mixed Content
Even with a correct server response, browsers can still block or obscure changes.
Caching is the obvious one. If you changed the file but the browser keeps serving an old cached response, hard refresh while testing: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac).
Mixed content is another common cause. If your page loads over HTTPS and your image URL uses HTTP, modern browsers may block it.
<img src="http://example.com/image.jpg" alt="Blocked on HTTPS">
Extensions, privacy tools, or corporate filters can also block images based on URL patterns. If a user can’t load images but you can, this is worth checking.
Writing Effective Alt Text and Fallbacks
Images fail sometimes. That’s why alt text exists–it’s not just a tool for website accessibility.
Every image on a webpage should have alt text associated with it, as it helps screen readers provide additional context to users who may be visually impaired. But it’s also a common fallback tool that can let users know what the image is supposed to represent, in case it fails to load.
Write alt text that describes the image’s purpose on the page: is it a specific person giving a speech, or a product being used? It doesn’t need to be overly specific, as long as the meaning is conveyed. If the image is purely decorative, use alt="" so screen readers will skip it.
<img src="chart-q3-sales.png" alt="Q3 sales increased 23% compared to Q2"> <img src="decorative-border.png" alt="">
The title attribute is optional, not a replacement for alt, and should not be identical to the alt text. It’s mostly used to add additional context to an image when the user hovers over it as a tooltip, so it shouldn’t contain any important information.
Debugging with Browser DevTools
DevTools will tell you what happened. Use the browser’s evidence instead of guessing. Start with the Network panel:
1. Open DevTools → Network.
2. Reload the page.
3. Filter to images (often “Img”).
4. Click the failed request and check the status code and headers.
Then check the Console. CORS and mixed content errors are often surfaced there, even when a request doesn’t complete normally.
Finally, inspect the element to confirm the resolved URL. If JavaScript modifies src, what you see in the HTML source may not match what the browser requested.
document.querySelector("img").complete
document.querySelector("img").naturalWidth
If naturalWidth is 0, the browser didn’t load image data.
How Cloudinary Simplifies Image Delivery
Cloudinary is a cloud-based media platform that handles image hosting, transformation, optimization, and delivery through a single URL-based API. You upload an asset once, then deliver it consistently via CDN.
The big change is URL stability. You aren’t debugging file paths across environments because you’re not shipping images via “where did this file land on this server.”
from cloudinary import CloudinaryImage
url = CloudinaryImage("folder/hero-image").build_url() print(url)
You can also let Cloudinary pick formats and quality automatically. f_auto,q_auto serves modern formats when supported and falls back cleanly when they aren’t.
<img src="https://res.cloudinary.com/demo/image/upload/f_auto,q_auto/sample.jpg" alt="A bee pollinating pink flowers">
Need a different size? You can request it via URL parameters instead of managing multiple files.
<img
src="https://res.cloudinary.com/demo/image/upload/w_800/sample.jpg"
alt="A bee pollinating pink flowers">
You still need to use the URLs correctly, but you’re not also maintaining the underlying serving rules, headers, and variant pipelines by hand.
Wrapping Up
When an HTML image is not displaying instead of text, it’s usually a path issue, a naming mismatch, a server response problem, or a browser block. You can debug it quickly with DevTools once you know what to look for.
The bigger problem is repetition. The same classes of issues keep showing up as your asset library grows, your environments multiply, and performance requirements get stricter.
Cloudinary reduces that operational surface area. You upload once, deliver via stable URLs, and request variants through the URL instead of building and maintaining that machinery yourself. If image delivery is taking more time than it should, Cloudinary’s free tier is a reasonable place to start.
Streamline your media workflow and save time with Cloudinary’s automated cloud services. Sign up for free today!
Frequently Asked Questions
Why does my image show alt text in one browser but not another?
Browsers differ on caching and security behavior. One browser may use a stale cached response while another isn’t. Some browsers also block mixed content more aggressively. Check the Network and Console tabs in the browser where it fails.
How do I fix a 403 error on images?
A 403 usually means the server is refusing access. The common causes are file permissions, directory permissions, or access rules. Verify the server user can read the file and that the server is configured to serve it. With Cloudinary, delivery headers and access behavior are handled for you unless you configure restricted assets.
Can broken images affect SEO?
Yes, broken images can hurt page experience and prevent search engines from indexing image content. Reliable, consistently accessible image URLs help avoid that, especially when you’re serving images via a CDN.
