• Nikao Yazılım Hizmetleri
logo

Fixing Flutter UTF-8 decode errors

  : :   Blog   : :   Solution   : :   Fixing Flutter UTF-8 decode errors
Explains why Flutter may throw FileSystemException: Failed to decode data using encoding 'utf-8' and how to resolve it.

One day a Flutter project stops opening for no apparent reason and the console shows FileSystemException: Failed to decode data using encoding 'utf-8'. It has nothing to do with your latest change, and restarting does not help.

The cause: Dart and Flutter keep intermediate files to speed up builds (package resolution data, build cache). If one of them is corrupted by an interrupted write (a full disk, a sudden shutdown, a killed process) the tooling tries to read it, fails to decode it as text, and reports this error.

The fix is not to repair the file but to delete the corrupted cache; the tools regenerate it. The steps below do that in a safe order. Try them before rebuilding the project from scratch: your source code is untouched, only generated files are removed.

During a project you run with Flutter, you may sometimes face the error below.
Things like "was it the last change I made, let me close and reopen it" turn out to be fruitless.

Unhandled exception:
FileSystemException: Failed to decode data using encoding 'utf-8', path = '...'

Before reformatting, it will be helpful to perform the following steps
  1. Close your project.
  2. For Windows
    C:\Users\\.dart-tool
    C:\flutter\the\folder\where\your\project\is\.dart-tool
    C:\Users\\.pub-cache
    For macOS
    /Users//.dart-tool
    /Users/flutter/the/folder/where/your/project/is/.dart-tool
    /Users//.pub-cache
    delete these folders completely.
  3. Reopen your project.
  4. flutter clean
  5. flutter pub get

Short guide

When to use it

Flutter UTF-8 decode errors often come from corrupted generated files or a file saved with the wrong encoding, not from the source code you just wrote. Separate cache problems from real project files first.

What to watch

  • Read the file path in the error message; it tells you whether the problem is in cache or source.
  • Commit or back up your source changes before cleaning generated files.
  • If an API or file read is involved, check response headers and the actual encoding.

Common mistake

Recreating the project from scratch is usually wasted effort. Start by identifying the corrupted file and the encoding source.

A note for long-term fixes

When fixing an error, hiding the message is rarely enough. Version, operating system, dependencies, encoding, server settings and logs should be reviewed together. For a long-term fix, it is better to review the environment, dependencies and data flow together.