How to Debug HTML and Fix Common Errors
Debug HTML by comparing the live DOM with your source, validating the document, and fixing the markup that caused the mismatch.
To debug HTML, reproduce the problem, inspect the affected element in your browser’s DevTools, compare the live DOM with the source, and run the document through an HTML validator. Fix the underlying markup, then reload and inspect again. A page can look mostly correct even when its HTML is malformed: browsers try to recover and may build a DOM that differs from the source.
1. Reproduce the problem and inspect the live DOM
- Reload the page and identify the exact content or element that looks wrong. Note what you expected to see and what appeared instead.
- Open your browser’s developer tools and select the affected element in the Elements or Inspector panel.
- Follow the element’s parent and child nodes. Check whether the browser placed the content inside the elements you intended.
- Use the inspector’s link between the DOM tree and the page to confirm which rendered area corresponds to the selected node.
The DOM inspector shows the structure the browser currently uses. It may include the browser’s recovery from malformed markup and changes made by JavaScript after the page loaded. It is not necessarily a literal view of your HTML file. See MDN’s HTML debugging guide.
2. Compare the DOM with the source
Use View Source or open the original file to inspect the HTML received from the server. Compare the relevant section with the live DOM:
- Source is already wrong: inspect the tags and attributes around the affected content.
- Source looks right but the DOM differs: check for malformed markup that the browser repaired, then check whether JavaScript changed the page after load.
- DOM structure is right but the page looks wrong: investigate CSS, layout, and computed styles in DevTools.
View Source answers “What HTML did the server send?” The DOM inspector answers “What structure is the browser using now?” Those can differ because of parser recovery or runtime script changes. MDN covers this distinction in its CSS debugging guide.
3. Validate the complete document
Run the whole document through an HTML validator rather than checking only the visible fragment. The Nu HTML Checker accepts a URL, an uploaded file, or direct input. Use each diagnostic’s line and column as a starting point, then inspect the surrounding markup; an earlier unclosed tag can make later lines appear to be the problem.
- Choose URL validation for a deployed page, file validation for a local document, or direct input for a small reproduction.
- Read the first diagnostic and find its location in the original source.
- Inspect nearby opening tags, closing tags, quotes, and nesting order.
- Correct the source and validate again. Continue until the relevant diagnostics are resolved.
The W3C tools page lists the Nu HTML Checker and other validation tools. A clean validator result helps establish that the markup conforms; it does not prove that CSS or JavaScript produces the intended appearance.
4. Fix common HTML errors
Unclosed elements
A missing closing tag can make later content part of an element unexpectedly. For example, if emphasis is never closed, the browser may keep applying it beyond the intended words.
<p>Please read the <strong>important notice.</p>
<p>This paragraph may be parsed differently than intended.</p>Close the element where its content should end:
<p>Please read the <strong>important notice</strong>.</p>
<p>This paragraph is separate.</p>Incorrect nesting
Close nested elements in the reverse order from which they were opened. Crossing the order can prompt the browser to repair the tree.
<strong>Important <em>read this</strong></em>Correct nesting:
<strong>Important <em>read this</em></strong>Malformed or unclosed attributes
Put attribute values in matching quotes. A missing quote can cause following text to be read as part of the value, so a link may not behave as expected.
<a href="https://example.com>Open the example</a>Corrected:
<a href="https://example.com">Open the example</a>Unexpected content placement
If an element appears under an unexpected parent in the DOM, inspect the tags immediately before it. A missing close tag or a close tag in the wrong place can shift the apparent boundaries of following sections. Use the validator’s earliest relevant diagnostic and trace the nesting from there.
5. Separate HTML problems from CSS and JavaScript
When the DOM structure matches the intended document but the result still looks wrong, move to the relevant DevTools panels:
- CSS: inspect computed styles, matched rules, inherited values, and layout. A hidden element, unexpected margin, or overridden rule can resemble a markup problem.
- JavaScript: check the console for errors and determine whether scripts add, remove, or move nodes after load.
- Network or loading: confirm the document and its resources loaded successfully before diagnosing their rendered result.
MDN’s guide to common HTML and CSS problems discusses using editor linting and browser tools to narrow down the cause. Fix one layer at a time so you can tell whether the source markup, styling, or runtime behavior changed the result.
6. Capture the page when you need a visual record
A screenshot can help document the visible symptom or compare a page before and after a markup fix. It shows the rendered page, though it cannot tell you whether the source is valid or explain why the DOM differs. Use DevTools and a validator for those questions.
For a local screenshot without a service, open the page in your browser and capture it with the operating system’s screenshot shortcut. For repeatable browser automation, use a browser automation tool and wait for the page state you need before saving the image. Keep viewport size and page state consistent when comparing captures.
Or skip the browser setup
For a hosted page, ScreenshotNeo can return a screenshot in one request. It accepts consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. See ScreenshotNeo and the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
timeout=90,
)
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(`Screenshot request failed: ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
// Save bytes with your runtime's file API.Sign up for 1,000 free screenshots a month, with no card.
7. Troubleshooting checklist
| Symptom | Likely cause | What to do |
|---|---|---|
| Text or formatting continues too far | An element was not closed where intended | Inspect the surrounding tags, add the correct closing tag, then validate. |
| A node appears under the wrong parent | Incorrect nesting or a missing close tag | Compare source and DOM; correct the opening and closing order. |
| A link is missing or its target is odd | A malformed or unclosed quoted attribute | Check the full attribute value and matching quotes. |
| The DOM differs from View Source | Browser recovery or JavaScript mutation | Validate source first, then inspect scripts that run after load. |
| Validation reports errors far from the edit | An earlier error may have changed how later markup is parsed | Start at the earliest relevant diagnostic and inspect preceding tags. |
| Markup validates but the page still looks wrong | CSS rules, layout, or script behavior | Inspect computed styles and console errors; debug that layer separately. |
| A screenshot shows a challenge or blank content | The destination may be showing a bot check or may not have loaded usable content | Inspect the page in a browser and use the screenshot response verdict and billing headers when available. |
8. Make debugging faster and more reliable
- Keep a minimal reproduction: reduce the source to the affected structure while preserving the error. This makes nesting mistakes easier to spot.
- Validate after each structural change: several simultaneous edits make it harder to identify which correction fixed the issue.
- Use editor linting: an editor-integrated linter can surface problems while you work; MDN includes this among the available debugging approaches.
- Compare like with like: for visual checks, use the same URL, viewport, page state, and loading conditions. A screenshot is useful for appearance comparisons, but it is not a validator.
- Account for runtime changes: a DOM captured after scripts run may differ from the initial server response. Check both when the issue is timing-dependent.
Validation and inspection are inexpensive ways to narrow down a defect before spending time on unrelated CSS or scripts. For automated screenshot workflows, consider page readiness and repeatability: wait for the state relevant to the issue, and treat a capture of a blank or challenge page as evidence about what loaded, not proof that the HTML source is malformed.
FAQ
Does a page that renders correctly have valid HTML?
No. Browsers can recover from malformed markup, so rendering alone does not establish that the source conforms.
Should I fix every validator message?
Use the diagnostics to find source problems, starting with the earliest relevant one. Fix errors that explain the observed structure or behavior, then validate again; the validator is a diagnostic aid, not a substitute for checking the intended result.
Can a screenshot tell me what is wrong with my HTML?
It can show the visible symptom. To find structural errors, inspect the live DOM and source and run a validator.
Why do source and the inspector show different content?
The browser may have repaired malformed markup, or JavaScript may have changed the document after it loaded. Compare the initial source with the live DOM and inspect runtime scripts.
