Debugging Web Projects

Debugging Mindset

Debugging means finding the difference between what you expected and what the browser is actually doing. The goal is not to guess faster. The goal is to make the problem smaller until the cause becomes visible.

Do not change five things at once. Describe the symptom, inspect the page, test one likely cause, refresh, and keep track of what changed.

A calm debugging process is a professional skill. The browser gives you clues; your job is to read them before rewriting the project.

The Debugging Loop

CSS Is Not Applying

When CSS is not working, first decide whether the stylesheet failed to load or whether the selector/rule is not matching the element.

<!-- HTML -->
<section class="project-card">...</section>

/* CSS bug: selector does not match the class */
.projectcard {
  border: 1px solid currentColor;
}

/* Fix */
.project-card {
  border: 1px solid currentColor;
}

Images or Links Are Broken

Broken images and links are usually path problems. The path starts from the file that contains the src or href, not from the project folder you see in VS Code.

• Use the Network panel to find missing files with 404 status codes.
• Check spelling and capitalization exactly. Published sites are often case-sensitive.
• Do not use local computer paths like C:/Users/name/Desktop/image.jpg in HTML.
• Open the image or linked page URL directly in the browser to confirm it exists.

<!-- index.html is beside the images folder -->
<img src="images/hero.jpg" alt="Student portfolio homepage">

<!-- about/index.html is inside an about folder -->
<img src="../images/hero.jpg" alt="Student portfolio homepage">

JavaScript Does Nothing

When JavaScript stops working, open the console before editing. Read the first error first. Later errors may be caused by the first one.

Uncaught TypeError: Cannot read properties of null

Meaning:
JavaScript tried to use an element that was not found.

First checks:
1. Does the selector match the HTML?
2. Does the script run after the HTML exists?
3. Is the script on the correct page?

Common JavaScript Selector Bug

If querySelector() cannot find the element, it returns null. Calling methods on null causes the script to fail.

<!-- HTML -->
<button class="menu-button" type="button">Menu</button>

// JavaScript bug: selector is missing the hyphen
const button = document.querySelector('.menubutton');
button.addEventListener('click', openMenu);

// Fix
const button = document.querySelector('.menu-button');
button.addEventListener('click', openMenu);

Script Loading Order

If JavaScript runs before the HTML exists, selectors may return null. A simple fix is to place the script at the end of the body or use the defer attribute when loading an external script.

<!-- Good option: defer external JavaScript -->
<script src="script.js" defer></script>

<!-- Good option: place script before closing body tag -->
<script src="script.js"></script>
</body>

HTML Validation

Invalid HTML can create layout, styling, and accessibility problems that look like CSS or JavaScript bugs. Use a validator when the page behaves strangely and the cause is not obvious.

Published Site Debugging

Always test the published URL. Local preview and GitHub Pages are different environments, so a site can work locally and fail online.

Mobile Overflow Debugging

Horizontal scrolling usually means something is wider than the viewport. Use the responsive device toolbar and inspect the widest-looking element.

• Look for fixed widths like width: 1200px.
• Check large images, tables, long words, and wide flex rows.
• Use max-width: 100% on images and media.
• Allow grids and flex layouts to wrap or change at smaller widths.

img,
video {
  max-width: 100%;
  height: auto;
}

.card-grid {
  display: grid;
  gap: 1rem;
  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
}

Do Not Debug by Shotgun

Debugging Checklist

• Describe the exact symptom before editing.
• Inspect the element instead of guessing which CSS rule wins.
• Use the Console for JavaScript errors.
• Use the Network panel for missing CSS, JavaScript, images, and pages.
• Validate HTML if the page structure behaves strangely.
• Check file paths from the current HTML file.
• Test one change at a time.
• Commit, push, and test the live URL before submitting.