Flutter UTF-8 decode hatası çözümü

Flutter’da FileSystemException: Failed to decode data using encoding 'utf-8' hatasının neden oluşabileceğini ve nasıl giderilebileceğini anlatır.

Flutter projesi bir gün sebepsizce açılmamaya başlar ve konsolda FileSystemException: Failed to decode data using encoding 'utf-8' hatası görürsünüz. Son yazdığınız kodla ilgisi yoktur; projeyi kapatıp açmak da işe yaramaz.

Sebep şudur: Dart ve Flutter, derlemeyi hızlandırmak için ara dosyalar tutar (paket çözümleme bilgisi, derleme önbelleği). Bu dosyalardan biri yarıda kalmış bir yazma yüzünden bozulursa (disk dolmuş, bilgisayar kapanmış, işlem sonlandırılmış olabilir) araç dosyayı okumaya çalışır, metin olarak çözemez ve bu hatayı verir.

Çözüm dosyayı onarmak değil, bozulan önbelleği silmektir; araçlar onları yeniden üretir. Aşağıdaki adımlar bunu güvenli sırayla anlatıyor. Projeyi sıfırdan kurmadan önce mutlaka deneyin: kaynak kodunuza dokunulmaz, yalnız üretilmiş dosyalar silinir.

Flutter ile yürüttüğünüz bir proje esnasında bazen Aşağıdaki hata ile karşı karşıya kalabilirsiniz.
Acaba son yaptığım değişiklikmi sebep oldu, bir kapatıp açayım gibi işlemler sonuçsuz kalır.

Unhandled exception:

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

Format atmadan önce aşağıdaki işlemleri yapmanız yararlı olacaktır

Projenizi kapatın.
Windows için
C:\Users\<KullanıcıAdı>\.dart-tool
C:\flutter\projenizin\bulunduğu\klasör\.dart-tool
C:\Users\<KullanıcıAdı>\.pub-cache
MacOS için
/Users/<KullanıcıAdı>/.dart-tool
/Users/flutter/projenizin/bulunduğu/klasör/.dart-tool
/Users/<KullanıcıAdı>/.pub-cache
klasörlerini tamamen silin.
Projenizi yeniden açın.
flutter clean
flutter pub get

Kısa rehber

Ne zaman kullanılır?

Flutter UTF-8 decode hatası çoğu zaman kaynak koddan değil, bozulmuş ara dosyalardan veya yanlış karakter kodlamasıyla kaydedilmiş bir dosyadan çıkar. Bu yüzden önce panik yapmadan cache ve dosya durumunu ayırmak gerekir.

Dikkat edilecekler

Hata mesajındaki dosya yolunu dikkatle okuyun; sorun proje dosyasında mı cache içinde mi anlaşılır.
Cache temizliği yapmadan önce kaynak kod değişikliklerinizi commit veya yedekle güvenceye alın.
API veya dosya içeriği okuyorsanız response header ve gerçek encoding bilgisini kontrol edin.

Sık yapılan hata

Sorunu Flutter'ın kendisinde arayıp projeyi baştan kurmak çoğu zaman zaman kaybettirir. Önce bozuk üretilmiş dosyaları ve encoding kaynağını ayırmak daha hızlıdır.

Kalıcı çözüm için not

Hata çözümü yaparken yalnız hata mesajını kapatmak yeterli değildir. Sürüm, işletim sistemi, bağımlılıklar, karakter kodlaması, sunucu ayarı ve log kayıtları birlikte incelenmelidir. Nikao, web tabanlı projelerden mobil uygulamalara kadar bakım ve modernizasyon süreçlerinde bu yaklaşımı kullanır.