Why HTML Background Images Are Not Working and How to Fix Them

A missing HTML background image usually has one of four causes: the CSS rule does not apply, the url() points to the wrong place or a failed request, the element has no visible area, or another background declaration covers or resets it. Start in browser DevTools: inspect the element, check the computed background-image, then inspect the image request in the Network panel.

Use this minimal working example as a known-good baseline:

<!doctype html>
<html lang='en'>
<head>
  <meta charset='utf-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
  <title>Background image test</title>
  <style>
    .hero {
      min-height: 24rem;
      background-color: #263238;
      background-image: url('./images/hero.jpg');
      background-position: center;
      background-repeat: no-repeat;
      background-size: cover;
    }
  </style>
</head>
<body>
  <section class='hero'></section>
</body>
</html>

1. Confirm that the CSS rule applies

Open DevTools, inspect the element, and look at both the Styles and Computed panels.

Check the CSS rule, the network request, and the element’s painted area in that order.

Search the computed properties for background-image.
If it is none, check that the selector matches the element and that the declaration is valid.
Look for a crossed-out declaration. A more specific selector, a later rule, or an inline style may win in the cascade.
Search for a later background: shorthand. It can reset an earlier background-image.

Do not add !important first. Find the declaration that wins and fix the selector order or specificity.

/* This works when no later rule overrides it. */
.card {
  background-image: url('./images/card.jpg');
}

/* This later shorthand resets the image to none. */
.card {
  background: #fff;
}

/* Keep all required values in the final declaration. */
.card {
  background: #fff url('./images/card.jpg') center / cover no-repeat;
}

2. Resolve the URL from the stylesheet location

A relative URL in an external stylesheet is resolved relative to that stylesheet, not relative to the HTML file. If css/site.css contains url('../images/hero.jpg'), the browser looks for images/hero.jpg relative to css/site.css.

File layout	CSS declaration	Resolved target
`/index.html` `/css/site.css` `/images/hero.jpg`	`url('../images/hero.jpg')`	`/images/hero.jpg`
`/pages/about.html` `/css/site.css` `/images/hero.jpg`	`url('../images/hero.jpg')`	Still `/images/hero.jpg`; the HTML file location does not change it.

In Network, reload the page and filter by Img. Open the requested URL directly. A 404, 403, redirect to an HTML error page, or a blocked request explains why the background cannot be painted. Check filename capitalization and extension on case-sensitive servers.

When a page is opened with file://, local resources can run into browser origin restrictions. Serve the directory through your development server instead:

python3 -m http.server 8000

Then visit http://localhost:8000/ and inspect the request again.

3. Check that the element has a visible box

A background image does not create layout size. An empty element with no width or height can have nothing to paint into, even when the image request succeeds.

.hero {
  width: 100%;
  min-height: 24rem;
}

.banner {
  min-height: 100vh;
  padding: 4rem 1.5rem;
}

/* Content can also give the element height. */
.card {
  padding: 2rem;
}

Use the Elements panel’s box model and Layout view. If width or height is zero, fix the layout before changing background-size.

4. Check shorthand, layers, and overlays

The background shorthand sets color, image, position, size, repeat, attachment, and origin values. A later shorthand can erase an image. Multiple backgrounds are layered: the first image listed is closest to the user, so an opaque upper layer can hide everything below it.

/* The first layer is on top. */
.hero {
  background-image:
    linear-gradient(rgba(0, 0, 0, .35), rgba(0, 0, 0, .35)),
    url('./images/hero.jpg');
  background-position: center, center;
  background-size: cover, cover;
  background-repeat: no-repeat, no-repeat;
}

/* A solid upper layer hides the image. */
.hero {
  background-image: url('./images/hero.jpg'), #fff;
}

Temporarily remove overlays, pseudo-elements, and positioned children with opaque backgrounds. Then inspect the final computed values rather than only the rule you intended to use.

5. Adjust sizing and positioning after the request succeeds

Once Network shows a successful image response and the element has a box, tune how the browser paints it.

Responsive cropping changes with the box ratio; adjust the focal point after the image loads.

Setting	Use it when	Trade-off
`cover`	The box must be filled.	The image may be cropped.
`contain`	The entire image must remain visible.	Empty space may remain.
`auto`	You want the intrinsic image size.	The box may not be filled.
`background-position`	The subject is cropped incorrectly.	Changing the focal point changes what disappears at other widths.

.hero {
  background-color: #263238;
  background-image: url('./images/hero.jpg');
  background-repeat: no-repeat;
  background-size: cover;
  background-position: 50% 35%;
}

@media (max-width:  FortyRem) {
  .hero {
    background-position: 65% center;
  }
}

Replace FortyRem with a numeric value such as 40rem; it is written that way above only to keep the example visually distinct. A valid media-query version is:

@media (max-width: 40rem) {
  .hero { background-position: 65% center; }
}

6. Decide between a CSS background and an HTML image

Use a CSS background for decorative presentation such as a texture or hero backdrop. Background images are not exposed as meaningful image content to assistive technology. If the image conveys information, use an HTML image with useful alternative text.

<img src='./images/chart.png' alt='Monthly signups increased from January through June'>

Keep a background-color fallback so text remains readable when the image is unavailable.

7. A complete diagnostic page

Save this as index.html, place an image at images/hero.jpg, and serve it over HTTP:

<!doctype html>
<html lang='en'>
<head>
  <meta charset='utf-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
  <style>
    :root { color-scheme: light dark; }
    body { margin: 0; font: 16px/1.5 system-ui, sans-serif; }
    .hero {
      display: grid;
      place-items: end start;
      min-height: 60vh;
      padding: 2rem;
      color: white;
      background-color: #263238;
      background-image: linear-gradient(rgba(0,0,0,.3), rgba(0,0,0,.3)), url('./images/hero.jpg');
      background-position: center;
      background-repeat: no-repeat;
      background-size: cover;
    }
  </style>
</head>
<body>
  <main class='hero'>
    <h1>Inspect the rule, request, and box</h1>
  </main>
</body>
</html>

8. Troubleshooting checklist

Symptom	Likely cause	Fix
Computed value is `none`	Selector mismatch, invalid CSS, or an override	Check matching selectors, crossed-out rules, and later shorthands.
Network request is 404	Wrong relative path or filename case	Resolve from the CSS file’s directory and correct the path.
Network request is 403	Server permissions or hotlink protection	Fix asset permissions or serve the asset from an allowed origin.
No request appears	Rule is not applied, image is cached, or the declaration is invalid	Check computed styles, disable cache while DevTools is open, then reload.
Request succeeds but nothing shows	Zero-height element, transparent image, crop, or covering layer	Inspect dimensions, remove overlays, and test `background-size: contain`.
Works inline but fails in external CSS	URL is resolved from a different directory	Recalculate the path relative to the stylesheet.
Works on one machine only	Case-sensitive path, stale cache, or local `file://` behavior	Use an HTTP server, hard reload, and verify the exact request URL.
Image is behind a color or gradient	Opaque background layer or pseudo-element	Inspect stacking order and make the upper layer transparent.

9. Performance, reliability, and cost

Use appropriately sized, compressed assets. A large background delays the page even when the CSS is correct.
Prefer modern formats where your browser support allows them, and keep a solid color fallback.
Do not use background-attachment: fixed by default on mobile; it can be expensive to render and behaves differently across browsers.
Test narrow and wide viewports because cover crops different regions as the aspect ratio changes.
For automated visual checks, capture the page only after the image request has completed and the layout has settled.

10. Or skip the browser setup

If you need a rendered screenshot to confirm how the background actually appears, ScreenshotNeo captures a URL through one API request. Its cleanup step accepts consent banners and removes 60+ known consent platforms, newsletter popups, and chat widgets before the capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Responses identify the page verdict and billing status with X-Page-Verdict and X-Billed headers. Its MCP server also gives Claude, Cursor, and other MCP clients take_screenshot, get_page_info, and capture_pdf tools.

See the ScreenshotNeo API docs for all options. The simplest call returns a WebP image:

curl -G 'https://api.screenshotneo.com/v1/shot' \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com \
  -o shot.webp

import requests

r = requests.get(
    'https://api.screenshotneo.com/v1/shot',
    params={'access_key': 'YOUR_API_KEY', 'url': 'https://example.com'},
    timeout=90,
)
r.raise_for_status()
open('shot.webp', 'wb').write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const bytes = await res.arrayBuffer();
await Bun.write('shot.webp', bytes);

ScreenshotNeo supports full-page and element captures, dark mode, device presets or custom viewports, retina scale, custom CSS and JavaScript, waits, request blocking, headers and cookies, geolocation, caching, signed links, async webhooks, bulk capture, PDFs, and HTML/CSS rendering. The Free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000.

Start with 1,000 free screenshots a month—no card required.

11. FAQ

Does `background-image` load before the element has content?

It can load, but the element still needs a non-zero painted area. Set a height, minimum height, padding, or content.

Should I use an absolute URL?

An absolute URL can help isolate a relative-path mistake, but it does not fix a blocked request, permissions error, or invalid asset.

Why does `cover` hide part of my image?

cover fills the box by cropping whichever dimension overflows. Change background-position or use contain when the full image matters.

Can a background image have alt text?

No. Use an HTML <img> with alternative text when the image communicates information.

How do I prove the final rendering in automation?

Wait for the image request and layout to settle, then capture the page at the target viewport. ScreenshotNeo can perform that rendered capture without maintaining your own browser setup.