PHP error guide

JSON malformed UTF-8: meaning and fix

error exception Affects: PHP 7.x–8.4; exception forms require JSON_THROW_ON_ERROR where shown Last verified:

Error summary

Fix text encoding at ingestion or deliberately substitute invalid sequences. Json_encode encounters bytes that are not valid UTF-8.

What it means

Fix text encoding at ingestion or deliberately substitute invalid sequences. Json_encode encounters bytes that are not valid UTF-8.

What the error means

This message means that json_encode encounters bytes that are not valid UTF-8. The exact signature distinguishes json malformed utf-8 from a generic application failure.

Why PHP produces it

The engine or service reports “JSON malformed UTF-8” because its required precondition was not met. Fix text encoding at ingestion or deliberately substitute invalid sequences.

PHP version notes

The json malformed utf-8 wording here is based on PHP 7.x–8.4; exception forms require JSON_THROW_ON_ERROR where shown; punctuation and exception class names can differ on older branches or vendor builds.

Most common causes

  • The immediate input or configuration reaches the specific condition: json_encode encounters bytes that are not valid UTF-8
  • The code path assumes the prerequisite for json malformed utf-8 has already been satisfied.
  • For json malformed utf-8, development and production differ in version, extension, permissions, paths, or service configuration.
  • An earlier operation returned an unchecked value that is consumed by the line reporting json malformed utf-8.

Minimal examples

BAD — reproduces the problem

php 
json_encode("\xB1\x31", JSON_THROW_ON_ERROR);

FIXED — safer pattern

php 
json_encode($text, JSON_THROW_ON_ERROR | JSON_INVALID_UTF8_SUBSTITUTE);

Step-by-step diagnosis

  1. Copy the complete “JsonException: Malformed UTF-8 characters, possibly incorrectly encoded” text and retain the first application stack frame.
  2. Reproduce json malformed utf-8 in the same SAPI and environment listed for this page.
  3. Before changing json malformed utf-8, inspect the preceding value or directive and verify its type, path, version, and permissions.
  4. Apply the narrow correction—fix text encoding at ingestion or deliberately substitute invalid sequences—then repeat the original request once.

Fixes

Correct the failing prerequisite

Fix text encoding at ingestion or deliberately substitute invalid sequences

php 
json_encode($text, JSON_THROW_ON_ERROR | JSON_INVALID_UTF8_SUBSTITUTE);

Fail explicitly at the boundary

Validate the condition before the operation that emits json malformed utf-8, and log a safe diagnostic without credentials or full production paths.

Common mistakes when fixing it

  • Suppressing json malformed utf-8 instead of correcting its upstream condition.
  • Testing json malformed utf-8 only with the CLI binary when the failing request runs under FPM or Apache.
  • Changing a global setting for json malformed utf-8 before confirming the site-specific effective configuration.

How to prevent it

  • Add a focused test that exercises the boundary responsible for json malformed utf-8.
  • Keep runtime versions, extensions, configuration, and deploy artifacts affecting json malformed utf-8 reproducible.
  • Validate external data and service return values before they can trigger json malformed utf-8.

Web server / environment notes

cli, fpm, linux. The failure occurs where json_encode encounters bytes that are not valid UTF-8

Tags: cli,fpm,linux

Categories

Relevant ZendStudio.net tools