How to Debug a Broken Web Page (Step-by-Step)

Learn a calm troubleshooting workflow for broken HTML, CSS, file paths, and JavaScript behaviour.

Why Pages Break in Different Ways

When learners say a page is broken, they often mean one of several different things. The page may load but look wrong. It may look fine but have a button that does nothing. It may be missing an image or stylesheet. Or it may fail so badly that the browser stops running JavaScript altogether.

That is why the first debugging step is not fix it. The first step is to identify the kind of failure you are seeing.

The Debugging Loop

Good debugging is not random. It follows a loop:

1. observe the symptom clearly
2. collect evidence from the browser
3. choose the most likely layer
4. make one small fix
5. retest and learn from the result

This loop matters because it keeps your thinking connected to evidence. When you skip straight to editing code, you often solve the wrong problem or create a new one on top of the first.

Start with the Console

If something suddenly stops working, open DevTools and check the Console before you rewrite anything. The console often tells you exactly what the browser already knows.

Uncaught ReferenceError: menuButton is not defined
Failed to load resource: the server responded with a status of 404
Uncaught TypeError: Cannot read properties of null

Each of those messages points in a different direction. A reference error often means a variable name is wrong or unavailable. A 404 points to a file path or missing file. A null error often means JavaScript is trying to use an element the browser did not find.

Inspect HTML and CSS Before Assuming the Browser Is Wrong

If the page loads but looks wrong, inspect the broken element. The Elements panel lets you check whether the HTML you expected is actually on the page. This is where you catch problems like:

• a class name in HTML that does not match the CSS selector
• a missing wrapper that the layout depends on
• a button rendered as the wrong element
• content appearing in a different order than expected

Once the structure looks right, move to the Styles and Computed panels. Check whether the rule is missing, crossed out, or overridden. That tells you whether the problem is absent CSS, conflicting CSS, or the wrong HTML hook.

<a class="nav-link">Menu</a>

.site-nav__link {
  color: #1f3a44;
}

Check Files and Paths When Assets Are Missing

If an image does not appear, a stylesheet is not loading, or a script never runs, do not stay only in the code editor. Open the Network panel and reload the page.

This is where you can see whether the browser asked for the file at all, whether it found it, and what path it tried to use. A missing stylesheet or script can make a whole page look broken even though the HTML is fine.

<link rel="stylesheet" href="css/style.css">
<img src="images/dining-room.jpg" alt="Dining room">
<script src="js/menu.js"></script>

Each of those references is a promise that the browser will find a file in that location. If the path is wrong, the browser cannot keep the promise, no matter how good the CSS or JavaScript is.

Test JavaScript Assumptions One by One

When a click handler or interactive feature stops working, the bug is often not in the whole script. It is usually in one assumption the script made.

Common examples include:

• the selector does not match any element
• the script runs before the element exists
• the variable name is misspelled
• an earlier error stops the rest of the script from running

const menuButton = document.querySelector('.menu-toggle');

console.log(menuButton);

menuButton.addEventListener('click', () => {
  console.log('clicked');
});

A Step-by-Step Checklist You Can Reuse

When a page breaks, run through this checklist in order:

1. Name the symptom: what exactly is wrong?
2. Check the Console: is the browser already showing an error?
3. Inspect the element: is the expected HTML actually present?
4. Check Styles and Computed: is the CSS missing or overridden?
5. Check Network: did a stylesheet, image, or script fail to load?
6. Test one assumption: what is the simplest thing that could be false?
7. Make one fix: change one thing only
8. Retest: what changed, and what does that tell you?

Recap

Debugging a broken page gets easier when you stop treating it like a personal failure and start treating it like evidence gathering. The browser can show you missing files, invalid assumptions, structure mismatches, and overridden styles. Your job is to read those clues in a calm order.

The real skill is not memorising every possible bug. It is learning a repeatable way to narrow the problem until the next step becomes obvious.