> For the complete documentation index, see [llms.txt](https://docs.codpeller.com/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codpeller.com/en/html-validator/troubleshooting.md).

# Troubleshooting

Use these steps when validation does not work as expected. A failed check is not, by itself, evidence that the webpage's HTML is invalid.

## 1. I cannot validate the current webpage

**Symptoms:** You cannot start a check, or the extension cannot obtain the page HTML.

**Possible cause:** Chrome may restrict access to the current tab, or the page may no longer be available to the extension. The exact reason depends on the tab and the message shown.

**Recommended action:** Open a regular HTTP(S) webpage that you are allowed to inspect, then open HTML Validator and try **Validate HTML** again. Read the displayed error before deciding what to change. See [User Guide](https://docs.codpeller.com/en/html-validator/user-guide.md) for the standard workflow.

## 2. “Local file access is disabled”

**Symptoms:** A local `file://` page shows **Local file access is disabled** instead of validation results.

**Possible cause:** Chrome has not granted HTML Validator access to local file URLs.

**Recommended action:**

1. Click **Open Chrome extension settings** in the warning, or open **Settings → Local HTML files → Manage in Chrome**.
2. In Chrome, enable **Allow access to file URLs** for HTML Validator.
3. Return to the local HTML tab. If Chrome has reloaded the extension, open the Side Panel again; refresh the file tab if needed.
4. Choose **Retry validation** when shown, or start validation again.

![Local file access warning showing the action to open extension settings](https://content.gitbook.com/content/Vo3wsnX9XzgpNcXIAwRg/blobs/Nq7V2QTUMl9HG1myuFed/images%2F13_local_access_disabled.png)

![Chrome extension setting for allowing local file URLs](https://content.gitbook.com/content/Vo3wsnX9XzgpNcXIAwRg/blobs/aTLPikaW45U92VG7cQB1/images%2F14_chrome_file_permission.png)

Chrome's exact permission label depends on the browser language. The images above are annotated guidance; refer to the actual Chrome permission control in your browser.

## 3. The local HTML file still cannot be read

**Symptoms:** Local-file validation remains unavailable even after changing the Chrome permission.

**Possible cause:** Chrome may have reloaded the extension, the Side Panel or file tab may need to be reopened, or access to that file may still be blocked. These are possibilities, not a diagnosis of every failure.

**Recommended action:** Confirm the permission is enabled for HTML Validator, reopen the local file tab and Side Panel, and retry. The extension does not substitute another HTML source when the file cannot be accessed.

## 4. W3C Nu returns HTTP 429

**Symptoms:** An online validation attempt reports HTTP **429** or a rate-limit message.

**Possible cause:** The external W3C Nu service or an intermediary may be limiting requests. A 429 response does **not** prove that your markup is invalid, nor does it identify a code regression by itself.

**Recommended action:** Do not send a rapid series of retries. Try again later. If you need a preliminary check without using the online service, select **HTML Tidy** and interpret its results with the limitations described in [User Guide](https://docs.codpeller.com/en/html-validator/user-guide.md). No fixed recovery time is guaranteed.

## 5. W3C Nu returns HTTP 503 or another network error

**Symptoms:** W3C Nu cannot complete a request, or reports a server/network failure.

**Possible cause:** The external service, your connection, or an intermediary may be temporarily unavailable. The error is not necessarily about HTML validity.

**Recommended action:** Check the connection, then retry later. If suitable for your task, use HTML Tidy for a basic local check. Do not treat a failed online request as a successful standards validation.

## 6. W3C Nu and HTML Tidy report different issues

**Symptoms:** The engines show different errors, warnings, or counts for the same page.

**Possible cause:** They use different approaches and have different support for modern HTML.

**Recommended action:** Use W3C Nu for standards-focused validation when external processing is appropriate. Use Tidy for basic local checks, remembering it may miss some conformance errors or flag valid modern markup. The results are not interchangeable.

## 7. Results still show the previous state

**Symptoms:** You edited HTML but see earlier findings, or an attempted **Revalidate** fails and old results remain visible.

**Possible cause:** Existing results describe the **previously captured snapshot**. A failed new request may leave an older result visible with an indication that it is stale.

**Recommended action:** Make sure the browser page reflects the changes (reload it if necessary), then click **Revalidate**. Confirm that a new validation completed before relying on its results. Do not mistake retained results for a new successful check.

## 8. Locate does not point to the expected place

**Symptoms:** **Locate** opens a position that does not match your source editor or does not highlight an element on the live page.

**Possible cause:** Locate uses line/column information in the **validated Current DOM snapshot**. JavaScript or later edits may have changed the page, and original source-file line numbers can differ.

**Recommended action:** Open **Results**, click **Locate**, and inspect the corresponding position on the **HTML** tab. If the page changed, run **Revalidate** and locate the issue again. Locate does not inspect a live DOM element or edit source code.

![HTML viewer with the validated error line highlighted](https://content.gitbook.com/content/Vo3wsnX9XzgpNcXIAwRg/blobs/p22PboDU6BJrbmP5yMyN/images%2F06_html_viewer_locate.png)

## 9. Some Chrome pages cannot be validated

**Symptoms:** Validation cannot access a browser-owned page or another restricted tab.

**Possible cause:** Chrome enforces access restrictions for certain pages. The exact scope varies by page type and browser rules.

**Recommended action:** Try a normal webpage or a local HTML file with the required permission. Do not assume that granting file URL access overrides restrictions on `chrome://` pages or all other protected contexts. The list of every restricted page is not part of this guide.

## 10. Warnings are missing from Results

**Symptoms:** Expected warnings are not visible in the result list.

**Possible cause:** **Show warnings** may be switched off in **Settings → Results**, or the validator may not have produced warnings.

**Recommended action:** Open Settings, turn on **Show warnings**, and review the results. Warning visibility does not change the underlying HTML.

![Settings with the Show warnings control](https://content.gitbook.com/content/Vo3wsnX9XzgpNcXIAwRg/blobs/Yzisd6Vq9OxgLSgJzGoY/images%2F08_settings.png)

## 11. The HTML Viewer does not highlight problem lines

**Symptoms:** **Locate** takes you to HTML but highlighted error lines are not shown.

**Possible cause:** **Highlight error lines in HTML viewer** may be turned off in Settings, or highlighting may not apply to the current result.

**Recommended action:** In **Settings → Results**, enable **Highlight error lines in HTML viewer** and review the validated snapshot. This setting affects the viewer, not the live webpage.

## 12. I need help with a different problem

**Symptoms:** The problem persists or does not match the cases above.

**Possible cause:** The information available may not be sufficient to identify a cause.

**Recommended action:** Open **Help & Feedback** (the **?** icon) and choose **Contact Support**, or email <validatorhtml@gmail.com>. Include the steps to reproduce the problem, the exact message, the engine used, and the result you expected.

![Help and Feedback menu with support options](https://content.gitbook.com/content/Vo3wsnX9XzgpNcXIAwRg/blobs/5RnQx6WcNEs4l5fU6TOv/images%2F10_help_feedback.png)

To prepare technical context, open **Settings → About HTML Validator → Copy diagnostic info**. This action **copies** information to your clipboard; it does not automatically send an email or attach data. Diagnostic information omits the webpage address and local file path. Before sending any copied issue text, URL, screenshot, or HTML, review it for sensitive content: a pathname or filename may reveal details even when query parameters and directory paths are omitted.

For general questions, see the [FAQ](https://docs.codpeller.com/en/html-validator/faq.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.codpeller.com/en/html-validator/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
