# Internal encoding declaration “utf-8” disagrees with the actual encoding of the document (“windows-1252”).
> Canonical HTML version: https://rocketvalidator.com/html-validation/internal-encoding-declaration-utf-8-disagrees-with-the-actual-encoding-of-the-document-windows-1252
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)
When a browser or validator reads your HTML document, it looks at the `` declaration to determine how to decode the bytes in the file. Every character encoding maps bytes to characters differently. UTF-8 and Windows-1252 share the same mappings for basic ASCII characters (letters A–Z, digits, common punctuation), but they diverge for bytes in the 0x80–0x9F range. Windows-1252 uses these bytes for characters like `€`, `"`, `"`, `—`, and `™`, while UTF-8 treats them as invalid or interprets them as parts of multi-byte sequences. When the declared encoding doesn't match the actual encoding, the validator raises this error, and browsers may render characters incorrectly.
This is a problem for several reasons:
- **Broken text display:** Characters like curly quotes (`" "`), em dashes (`—`), and accented letters (`é`, `ñ`) can appear as mojibake — sequences like `â€"` or `é` — confusing your readers.
- **Standards compliance:** The HTML specification requires that the declared encoding match the actual byte encoding of the file. A mismatch is a conformance error.
- **Accessibility:** Screen readers and other assistive technologies rely on correct character interpretation. Garbled text is unintelligible to these tools.
- **Search engines:** Encoding mismatches can cause search engines to index corrupted text, hurting your content's discoverability.
## How to fix it
The best approach is to **re-save your file in UTF-8 encoding**. Most modern text editors and IDEs support this:
- **VS Code:** Click the encoding indicator in the bottom status bar (it may say "Windows 1252"), select "Save with Encoding," and choose "UTF-8."
- **Sublime Text:** Go to File → Save with Encoding → UTF-8.
- **Notepad++:** Go to Encoding → Convert to UTF-8, then save the file.
- **Vim:** Run `:set fileencoding=utf-8` then `:w`.
After re-saving, make sure your `` declaration remains in the ``. The `` tag should appear as early as possible — ideally as the first element inside `` — because the browser needs to know the encoding before parsing any other content.
If your workflow or legacy system absolutely requires Windows-1252 encoding, you can change the declaration to `` instead. However, this is strongly discouraged. UTF-8 is the universal standard for the web, supports virtually all characters from all languages, and is recommended by the WHATWG HTML specification.
## Examples
### Incorrect — encoding mismatch triggers the error
The file is saved in Windows-1252, but the `meta` tag declares UTF-8:
```html
My Page
She said, "Hello!"
```
This produces the validator error: *Internal encoding declaration "utf-8" disagrees with the actual encoding of the document ("windows-1252").*
### Correct — file saved as UTF-8 with matching declaration
Re-save the file in UTF-8 encoding. The `meta` tag and the file's byte encoding now agree:
```html
My Page
She said, "Hello!"
```
### Alternative — declaration changed to match Windows-1252 file
If you cannot change the file encoding, update the `charset` declaration to match. This eliminates the mismatch error but is not the recommended approach:
```html
My Page
She said, "Hello!"
```
### Tips for preventing this issue
- Configure your editor to default to UTF-8 for all new files.
- If you copy text from Microsoft Word or other desktop applications, be aware that they often use Windows-1252 curly quotes and special characters. Pasting this text into a UTF-8 file is fine as long as your editor properly converts the characters to UTF-8 bytes when saving.
- Use `` as the very first element inside `` so the encoding is established before the browser encounters any other content.
- If your server sends an HTTP `Content-Type` header with a `charset` parameter, make sure it also matches — for example, `Content-Type: text/html; charset=utf-8`.