Content-Type troubleshooting

Content-Type charset errors

The charset parameter tells a receiver how the bytes of a message were encoded. It appears after the media type, separated by a semicolon: text/plain; charset=utf-8. Small syntax mistakes in that parameter, such as a missing semicolon, an empty value, a broken quote, or two conflicting charset declarations, can make the whole Content-Type value invalid or force a receiver to guess instead of reading the declaration.

Where the charset parameter belongs

In the media type grammar (RFC 2045 and RFC 6838), a Content-Type value is type/subtype, optionally followed by one or more ; parameter pairs:

text/plain; charset=utf-8

charset is one parameter among several, and parameters may appear in any order. The charset declaration is the part that describes the character encoding of the message body, which is why it matters most for text-based media types:

• application/rss+xml; charset=utf-8
• text/csv; header=present; charset=utf-8
• text/html; charset=utf-8

Three rules decide almost all charset syntax issues:

• A semicolon introduces the parameter. A space or any other separator breaks the grammar.
• The name is case-insensitive. CHARSET=utf-8 and charset=utf-8 are the same parameter; the canonical form writes it lowercase.
• The value is a token or a double-quoted string. Both charset=utf-8 and charset="utf-8" are valid.

Common charset syntax problems

These are the failures that show up in Content-Type values in the wild. Each example shows the broken form and the form that survives strict parsing.

Missing semicolon before the parameter

Broken: text/plain charset=utf-8

Without the semicolon, charset=utf-8 gets read as part of the subtype. A space is not a legal token character, so the value fails media type validation at the subtype.

Fixed: text/plain; charset=utf-8

Empty charset value

Broken: text/plain; charset=

A parameter must have a value after the equals sign. An empty value usually means the header was truncated, assembled from fragments, or built by a template that produced nothing for the name.

Fixed: text/plain; charset=utf-8

Name and value joined without "="

Broken: text/plain; charset utf-8

The equals sign is the only delimiter between a parameter name and its value. Without it, the validator reports a malformed parameter that stops at the next semicolon or at the end of the value.

Fixed: text/plain; charset=utf-8

Broken quoted value

Broken: text/html; charset="utf-8

A quoted-string must open and close with the same double quote. An unterminated quote can swallow the rest of the value, including any parameters that follow it.

Fixed: text/html; charset="utf-8" or text/html; charset=utf-8

Two charset declarations in one value

Broken: text/html; charset=utf-8; charset=iso-8859-1

Duplicate parameter names are ambiguous. Receivers cannot know which declaration applies, and their behavior varies: strict parsers reject duplicates outright, while lenient ones keep the first or the last occurrence. Remove the extra declaration at the source.

Fixed: text/html; charset=utf-8

Illegal characters in the parameter name

Broken: text/html; charset name=utf-8

Parameter names use token syntax, so a literal space cannot be part of the name. CorrectMIME applies a deliberately conservative parameter-token rule and may also reject extension constructs accepted by a more specialized HTTP field grammar. Characters such as % are not universally forbidden by MIME token grammar; support depends on the relevant header-field specification.

Fixed: text/html; charset=utf-8

Where charset declarations appear

The same charset parameter shows up in several places, and a mismatch between them is a common source of mojibake:

• HTTP responses: Content-Type: text/html; charset=utf-8 on the response header of a web page or API endpoint.
• Email messages: on the mail's Content-Type header, where the charset also combines with Content-Transfer-Encoding to describe how the body was encoded and transported.
• HTML documents: the <meta charset="utf-8"> declaration, which uses the same charset names. When the HTTP header and the meta tag disagree, browsers decide the winner by ruleset, and parts of the page can render with the wrong characters.
• Configuration: database connection strings, queue client settings, and file converters often carry a charset value that ends up merged into a Content-Type later.

Whatever the context, the syntax rules for the value are the same. Validate the exact string that will be sent, including any surrounding parameters.

How to fix a charset error, step by step

1. Copy the complete header value, for example the full Content-Type value without the field name.
2. Paste it into the Content-Type Validator and read the first reported issue.
3. Apply the correction at the source: fix the template, serializer, or header constant that produced the value.
4. Re-validate the corrected value and confirm the report is clean, or has only the warnings you accept.
5. Check the bytes still match the declared charset, especially after a serializer or transport layer changed.

What happens when a charset value is malformed

The consequences depend on how strict the receiving software is. A strict parser (some email clients, HTTP gateways, and XML processors) can reject the entire message when the Content-Type value is invalid. A lenient parser will drop the parameter and fall back to a default or guessed encoding. When the guessed encoding disagrees with the bytes, the result is mojibake: the document displays with wrong characters.

A malformed charset parameter is often a symptom of a header that was assembled from fragments by different code paths. Correct the value where it is produced, then re-validate the final header before deployment.

Character set names: what to write

Charset names are registered in the IANA character sets registry. The ones you will see every day include:

• utf-8, the default for modern web and API traffic
• us-ascii, a subset of UTF-8 for pure ASCII content
• iso-8859-1 and windows-1252, still common in older Western European content
• utf-16, used in some interchange formats

Name matching is case-insensitive, but lowercase utf-8 is what protocol tooling and signatures usually emit. Note that syntax validation and registration are separate things: a syntactically valid name that is missing from the registry will still pass a syntax check. CorrectMIME checks syntax; it does not look up the IANA registry.

JSON is a separate case: interoperable JSON uses UTF-8, and the application/json media type defines no charset parameter. CorrectMIME can check the generic syntax of a parameterized value, but it does not verify whether a particular media-type registration defines that parameter.

What CorrectMIME checks

• Separator and whitespace structure around the charset parameter, including lenient whitespace that CorrectMIME can normalize
• Presence of a value after =
• Quoted-string balance: opening and closing quotes, plus escaping
• Duplicate charset parameters, matched case-insensitively
• Media type token validity for the type, subtype, and structured suffix the parameter attaches to
• Warnings for empty parameter segments and for values longer than 512 characters

Canonical forms for common charset inputs

The canonical form lowercases the type, subtype, and parameter names, normalizes whitespace, removes quotes when the value is safe without them, and sorts parameters by name. Values are preserved exactly as written.