Start in your browser, not in the page editor: inspect the homepage element that should show the image, read its computed background-image, open the winning URL directly, and then check size, overlays, responsive rules, and caches. This sequence separates a bad selector or URL from an image that loads but is hidden. WordPress users should then follow the branch for their active theme and editor.
1. Identify the element and the winning CSS value
Open the public homepage, right-click the area where the image should appear, and choose Inspect. Select the actual body, hero, header, section, or page-builder container intended to carry the background. An image selected in an editor is not necessarily applied to the element rendered on the homepage.
- In Chrome DevTools, open the Styles pane and search for
background-imageorbackground. - Open the Computed pane and read the final
background-imagevalue. - Follow the source link beside that value to the rule that wins the cascade.
If the computed value is none or the property is absent, investigate the selector, theme setting, page-builder setting, or cascade before changing the image file. A declaration crossed out in Styles is inactive because another declaration wins.
What the result means
- No declaration: the rule is not loaded, the selector does not match, or the setting did not generate CSS.
- Crossed-out declaration: a later, more specific, inline, shorthand, or media-query rule overrides it.
- Valid URL in Computed: move to URL, dimensions, visibility, responsive, and cache checks.
2. Test the exact image URL
Copy the URL from the winning declaration and open it in a new tab. Check the exact filename, capitalization, directory, protocol, domain, and file extension. A missing file, an old staging-domain address, or a case mismatch can leave the background layer without a usable image.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute#1 Best Overall
Relative URLs are resolved from the stylesheet that contains them, not necessarily from the homepage URL. For example, a URL in /css/site.css is resolved relative to that stylesheet’s location. Fix the path or upload the asset to the intended location if the direct request fails.
WordPress theme.json paths
In the WordPress 6.6 behavior documented for theme.json, a path such as file:./assets/hero.jpg is resolved from the theme root even when theme.json is inside a subdirectory. Dot and double-dot navigation are not supported in these paths. An external absolute URL must remain available at that host.
On WordPress.com, an image hosted elsewhere is not copied into the Media Library. If that host removes or moves the file, the background stops working. Upload an asset to the Media Library when the site owner needs control over its availability.
3. Remove cascade and shorthand conflicts
Inspect every rule affecting the selected element. Common conflicts include a later selector with greater specificity, an inline style, a responsive media query, or a shorthand declaration such as background: #111; that resets background-image.
Use the Computed pane to identify the final value, then disable suspicious declarations one at a time. DevTools can flag invalid CSS and malformed url() syntax in the Styles or Sources views. Correct the rule that wins instead of repeatedly editing a lower-priority rule.
WordPress precedence caveat
WordPress 6.6 documentation describes Customizer backgrounds taking precedence over backgrounds set in theme.json or the Site Editor in the stated setup. Treat this as version- and theme-specific. Check which control is active on your installation and change the winning value there.
4. Check whether the image is loaded but invisible
A valid URL does not guarantee a visible background. Temporarily set a contrasting background color in DevTools and inspect the element’s box. Then check:
- Height: a section with zero height, collapsed children, or an unexpectedly small min-height has no area in which to show the image.
- Coverage: an opaque child, overlay, pseudo-element, or positioned layer may sit above the background.
- Responsive rules: a media query may replace or remove the image at the current viewport width.
- Crop and position: the subject may be outside the visible region.
- Repeat and size: the selected behavior may tile, contain, or crop differently than expected.
For WordPress controls, Cover, Contain, and Tile determine how an image fits. A block may not expose background controls at all; placing it inside a Group block that supports a background can provide the needed scope. Focal-point controls also affect which part of a cover image remains visible on different screens.
Recommended Free Tools
5. Verify the WordPress setting and scope
Use the path that matches the active theme. Menu names and availability vary between WordPress.com, self-hosted WordPress, themes, and versions.
| Setup | Where to edit | Typical scope | What to verify |
|---|---|---|---|
| Block theme | Appearance → Editor → Styles → Background | Site or supported template | That the homepage template uses the edited style and that the block supports backgrounds |
| Classic theme with Customizer support | Appearance → Customize | Theme background or site-wide setting | That the theme registers custom-background support and emits the rule |
| Page builder | The homepage section or hero’s background panel | That section or its responsive variants | Desktop, tablet, and mobile values, overlays, and section height |
| Theme code | Stylesheet, template, or theme.json |
Selector, template, or global styles | Path resolution, selector match, and generated CSS |
For a classic theme, the documented mechanism relies on theme support for a custom background, a custom-background body class, and output through wp_head(). If the Customizer option exists but no corresponding rule appears in the generated page source, inspect the theme’s support declaration and template output.
6. Save, publish, upload, and clear every cache
If the editor preview changes but the public homepage does not, check the deployment path before rewriting CSS.
- Confirm the setting was saved and the correct homepage, template, and active theme were edited.
- If you edited a file, verify it was uploaded to the expected server directory and that the upload replaced the old file completely.
- Check the site’s URL settings when an asset or stylesheet still points to a development domain.
- Bypass the browser cache with a hard reload or a private window.
- Purge server-side, CDN, and caching-plugin caches, then retest the public URL.
Compare the stylesheet and image URL in a fresh private window. A cached CSS file can preserve an old URL even after the editor displays the new one.
Choose a repair method deliberately
Use the active system’s supported control when it provides the required scope. Direct CSS is appropriate when you understand the selector, cascade, and responsive behavior.
| Method | Best for | Risk to check |
|---|---|---|
| Site Editor | Block themes and global or template backgrounds | A different template or block may be used on the homepage |
| Customizer | Classic themes that expose a background control | Its value may override theme.json or Site Editor settings in some WordPress 6.6 setups |
| Page-builder control | A single hero or section | Mobile-specific settings, overlays, and collapsed height |
| Stylesheet or custom CSS | Known selectors and precise responsive rules | Specificity, shorthand resets, invalid syntax, and maintenance after theme updates |
| Theme asset or Media Library | Assets the site should control | Incorrect relative roots or an external host becoming unavailable |
Common symptoms and fixes
The URL opens, but no image appears
Read Computed again, then inspect height, overlays, crop, position, and viewport-specific rules. Set a temporary contrasting color to prove whether the element occupies the expected area.
The rule is visible but crossed out
Follow the active declaration in Computed. Remove or adjust the later, more specific, inline, shorthand, or media-query rule that wins.
It works in the editor but not on the homepage
Check that you edited the published homepage template, saved the change, and cleared browser, plugin, server, and CDN caches.
Free tools Windows power users keep installed
One-click scans. No signup required.
Only mobile or desktop is broken
Resize the viewport and inspect the matching media query. Compare the winning declaration, image URL, section height, focal point, and overlay at each breakpoint.
The Customizer option is missing
The active theme may be a block theme, may not register custom-background support, or may use a builder instead. Use Appearance → Editor for a block theme or the builder’s section settings.
The image disappeared after moving files
Open the CSS URL directly and inspect the stylesheet’s directory. Correct the relative path or update the asset reference after confirming the intended upload location.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
For repeatable homepage captures, ScreenshotNeo provides a website screenshot API and MCP server. Its clean-shot workflow accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and whether the shot was billed.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsOne GET request returns PNG, JPEG, WebP, or PDF. The API supports full-page capture with lazy images loaded, CSS-selector element capture, device presets and custom viewports, retina scale, dark mode, PDF paper and margin controls, custom CSS and JavaScript, clicks, selector waits, delays, network-idle waits, request and resource blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, usage data, and an OpenAPI specification. Parameter names used by other screenshot APIs also work.
cURL
See the ScreenshotNeo documentation for authentication and options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o homepage.webpPython
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("homepage.webp", "wb").write(r.content)Node.js
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(`${res.status} ${res.statusText}`);
const fs = await import('node:fs/promises');
await fs.writeFile('homepage.webp', Buffer.from(await res.arrayBuffer()));The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is included on every plan. An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients. Create a free ScreenshotNeo account to try the capture without a card.
Final verification checklist
- The intended homepage element is selected in DevTools.
- Computed
background-imageshows the expected winning rule. - The exact URL opens and points to the intended file.
- No invalid CSS, shorthand reset, or stronger selector overrides it.
- The element has visible dimensions and is not covered by an opaque layer.
- Crop, focal point, repeat, and responsive values work at each breakpoint.
- The correct WordPress control, template, theme, or builder section was edited.
- The change was saved, uploaded, published, and all relevant caches were cleared.
Frequently Asked Questions
Should a homepage background be an img element instead?
Use an img when the picture is meaningful content that needs alternative text or independent loading behavior. Use a CSS background for decorative imagery behind content, provided contrast and accessibility remain acceptable.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Why does a background look different on high-density screens?
Viewport size, device-pixel ratio, the selected image variant, and cover cropping can all change the visible result. Compare the computed rule and rendered dimensions at the affected device width.
Can an external image host be a permanent WordPress solution?
It can work while the URL remains available, but the site owner does not control that asset. A Media Library or theme-managed file is safer when long-term ownership matters.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
