deploy notes
Websites

GitHub Pages images not showing: fix the exact requested path

Find the URL of a broken image, correct project-folder and filename-case mistakes, and verify the published image rather than guessing at cache or DNS.

Beginner4 min read
In this guide

If your GitHub Pages text loads but its images do not, start with the image URL the browser requested. A page can be in the right place while its image link points somewhere else.

This guide covers plain HTML on an existing GitHub Pages project site. You need to edit the page’s image link and access the files being published. It does not require a new host, package, or DNS change.

Find the failing image request

Open the published page in desktop Chrome or Edge. Right-click the page and select Inspect, then open Network. Reload the page with that panel open. Select the Img filter, then select the failed image request.

Read its Request URL and Status Code under Headers. If the request is 404, the requested file was not found. Open that URL in a new tab and compare it with the actual published file’s path.

If the HTML contains no image request at all, inspect the <img> element first: its src attribute is the address the browser uses. A 403, a security-policy error, or a request that succeeds but returns HTML needs a different fix; do not assume every blank image is a missing file.

Fix the project-folder mistake

Consider a fictional repository named recipe-notes, published at:

https://YOUR_USERNAME.github.io/recipe-notes/

Its published files are:

index.html
images/
  notebook.svg
pages/
  about.html

On index.html, this link is usually wrong for that project site:

<img src="/images/notebook.svg" alt="Blue notebook">

The first / means “start at the host’s root.” The browser requests https://YOUR_USERNAME.github.io/images/notebook.svg, leaving out /recipe-notes/.

From index.html, use a path relative to the page’s own folder:

<img src="images/notebook.svg" alt="Blue notebook">

That resolves to https://YOUR_USERNAME.github.io/recipe-notes/images/notebook.svg.

From pages/about.html, go up one folder first:

<img src="../images/notebook.svg" alt="Blue notebook">

../ means the parent folder. Copy the pattern that fits your page’s location; using the home-page path inside a nested page would ask for pages/images/notebook.svg.

A root-relative path can be correct on a user site or custom domain where the image really is under /images/. Do not remove every leading slash indiscriminately. Also check for a <base> element: if present, it changes the base URL used for relative paths.

Match the actual deployed filename

Compare the requested address with the file included in your publishing source or build output. All of these differences matter:

  • notebook.svg versus Notebook.svg;
  • .jpg versus .jpeg;
  • images versus Images;
  • a file on your computer versus a file actually committed and deployed.

Prefer simple filenames without spaces. If you rename an image, update the HTML that points to it too. For a case-only local rename, use a temporary different filename if necessary, then commit the final name and verify it on GitHub.

Do not use the repository’s normal file-view URL as an image source. That URL displays GitHub’s interface, not necessarily an image file that a browser can decode.

For an Astro, React, or other generated site, also inspect what the build actually emitted and its configured project base path. A source image absent from the deployed output cannot be repaired by refreshing the page. Follow that framework’s asset rules instead of copying these plain-HTML paths into every component.

Verify the published result

Save the corrected link in the site’s existing source, commit it through your usual workflow, and wait for the relevant Pages deployment to succeed in Actions.

Then repeat the check on the published page:

  1. Reload with Network open and select the image request.
  2. Confirm the Request URL includes the intended project folder and filename.
  3. Open the image URL directly. It should display the image, not HTML or a 404 page.
  4. Check the page itself and any nested page that uses the same image.

A normal successful response is 200; a valid cached response may be 304. The decisive result is the correct resource loading and displaying. If the direct image works but the page still shows an old path, try a hard refresh and check the page’s current HTML before changing more files.

Keep useful alt text in the <img> element. It describes the image when it cannot be seen, but it does not repair a broken URL. For a broader pre-launch check, verify links, forms, and narrow screens after the image is fixed.

← Back to website guides