Vercel Build Failed ve Deployment Blocked: Yaşadığım İki Sebep

Push'un yeni bir production sürümüne dönüşmemesi Vercel'de iki çok farklı biçimde olur. Birinde build çalışır ve düşer; hata ve log görürsünüz. Ötekinde build hiç başlamaz, log yoktur ve tek belirti değişikliğinizin canlıda olmamasıdır. İkisini de bu sitede birkaç hafta arayla yaşadım; ikincisi o kadar sessizdi ki kendi izlememiz her şeyi sağlıklı gösterdi.

Bu yazı ikisini ayırıyor, her biri için önce nereye bakılacağını gösteriyor ve hata ayıklarken akla gelen build cache sorularını da ele alıyor. Vercel ayrıntıları Kasım 2026'da dokümanından kontrol edildi; olaylar bu sitenin kendi geçmişinden.

İlk soru: build başladı mı?

Dashboard'da dağıtımı açın.

• Build logu var ve hatayla bitiyor. Build hatasıdır. İlk bölüme gidin.
• Log yok, yerinde bir mesaj paneli var. Build başlamadan durdurulmuş. Vercel dokümanı tipik sebepleri sayıyor: geçersiz bir vercel.json commit'lenmiş, Ignored Build Step atlatmış, commit ekip üyesi olmayan birinden gelmiş ya da bir Marketplace entegrasyon kaynağı önce hazırlanamamış. İkinci bölüme gidin.

Bu ayrım çok zaman kazandırır. İnsanlar var olmayan bir build logunu okuyarak bir saat harcıyor.

Durum 1: yerelde derleniyor, Vercel'de düşüyor

Vercel'in kendi önerisi önce yerelde build almak; kodunuzdaki ya da bağımlılıklardaki sorunları yakalar. İyi bir öneri ama yetmez, çünkü yerel build zaten orada duran node_modules'ü kullanır. Vercel sıfırdan kurar.

Bu sitede aradaki fark lock dosyası üzerinden ortaya çıktı. Sunucudaki eski bir npm sürümü temiz kurulum yaptı ve package-lock.json'ı yeniden yazdı: libc alanlarından oluşan bir blok silindi, toplam 161 satır. Yerel build geçti çünkü node_modules hazırdı. Vercel build'i düştü çünkü depodaki lock dosyasından kuruyor ve değişen dosya kabul edilmedi.

O günün tam hata metnini saklamadım, bu yüzden alıntılamayacağım. Söyleyebileceğim sebep ve kontrol:

git diff --stat -- package-lock.json package.json

Bağımlılıkları bilerek değiştirmediyseniz bu farkta iki dosya da görünmemeli. Lock dosyası değişmişse ve sebebini bilmiyorsanız geri alın:

git checkout -- package-lock.json

Çıkardığım kural: lock dosyasını üreten npm sürümünden farklı bir sürümle kurulum ya da güncelleme çalıştırmayın ve değişiklik yalnız içerik olsa bile her diff'te lock dosyasına bakın. Vercel'e daha yakın bir yerel kontrol istiyorsanız push'tan önce node_modules'ü silip temiz kurulumdan build alın. Daha yavaştır ve gerçeğe uyan tek test odur.

Hata gerçekte nerede

Vercel'in sorun giderme rehberi, son satırın çoğu zaman işe yarar olmadığını söylüyor. npm run build exited with 1 ile biten bir log yalnız build komutunun düştüğünü söyler. Yukarı kaydırıp ilk kırmızı "Error" satırını bulun; sebep genelde odur.

Aynı dokümandan bilinmesi gereken diğer build sınırları:

Bellek ya da diski aşan build iptal edilir ve Vercel bu durumda logda bir sistem raporu basar. VERCEL_BUILD_SYSTEM_REPORT=1 ortam değişkeni raporu her build için verir; build'i doğrudan öldürmeyen bellek yetersizliği olaylarını fark etmenize yardım eder.

Durum 2: dağıtım bloklandı, site hâlâ 200 dönüyor

Sessiz olan bu. GitHub'a push gider, hiçbir şey deploy olmaz, site önceki sürümü hatasız servis etmeye devam eder. Yalnız "sayfa 200 dönüyor mu" diye bakan her şey iyi olduğunu söyler.

Bu sitede otomatik bir işin commit'leri, hiçbir GitHub hesabına eşleşmeyen bir git e-postasıyla atılıyordu. Vercel commit'i bir kullanıcıya bağlayamadı ve art arda iki dağıtım Blocked kaldı. Site eski içerikle 200 vermeye devam etti.

Dokümandaki kural şu: özel depoda bir commit, yalnız yazarının Vercel projesine erişimi varsa deploy edilir. Hobby ekipte commit yazarı o Hobby ekibin sahibi olmalı; Vercel bunu sahibin giriş bağlantılarını commit yazarıyla karşılaştırarak doğruluyor. Pro ve Enterprise ekiplerde ekip üyeliğine bakılıyor. Hobby ekipler özel depolarda iş birliğini hiç desteklemiyor.

Dağıtım bloklandığında pratik kontrol listesi:

1. Commit'i atan makinede git config user.email çalıştırın.
2. Bu adresin Git sağlayıcı hesabınızda doğrulanmış bir e-posta olduğunu kontrol edin. Sağlayıcı commit'leri kullanıcılara bu eşleşmeyle atfeder.
3. Git sağlayıcınızın, projeye sahip Vercel hesabına bağlı olduğundan emin olun (Account Settings, Login Connections).
4. Birden fazla adresle commit atıyorsanız ek adresleri Vercel hesabınızın e-posta ayarlarına ekleyip doğrulayın.
5. Yeniden push edin. Bloklanmış dağıtım kendiliğinden düzelmez; çıkan, doğru yazarlı bir sonraki commit olur.

Otomasyon için çözüm, işe gerçek bir hesaba ait commit kimliği vermek. Benim durumumda yazar adı ayırt edilebilir kaldı (otomatik commit'leri geçmişte hâlâ seçebiliyorum), e-posta ise hesaba kayıtlı bir adrese çevrildi.

İzlemeniz bunu muhtemelen göremez

Daha faydalı ders doğrulama hakkında. Sayfayı isteyip 200 bekleyen bir deploy kontrolü, bloklanmış dağıtımda da geçer, çünkü önceki dağıtım servis edilmeye devam eder. Bende bu, fark edene kadar iki gece sürdü.

Çözüm, az önce değiştirdiğiniz içeriğin gerçekten canlıda olduğunu kontrol etmek. Yeni commit'i yansıtan bir şey seçin (başlık ya da sürüm metni) ve onu arayın:

curl -s https://example.com/some-page | grep -F "yeni commit'ten bir metin"

Bir ayrıntı daha: revalidate kullanan sayfalarda başarılı bir deploy sonrası bile CDN bir bölgede eski kopyayı tutabilir; yani değiştirdiğiniz sayfa bir süre eski görünebilir. Hiç önbelleklenmeyen bir yol, örneğin aynı içerikten üretilen dinamik bir metin uç noktası, test için daha güvenilirdir.

Build cache ve ne zaman atlanır

Build anlamsız biçimde düşmeye başlayınca biri cache'i temizlemeyi önerir. Doküman bunun ne yaptığını şöyle anlatıyor.

• Başarılı build cache'i kaydeder (bağımlılıklar, framework dosyaları). Sonraki build bunu install komutundan önce geri yükler.
• Başarısız build mevcut cache'i değiştirmez. Yani düşen bir build cache'i bozamaz.
• Cache anahtarı hesap ya da ekip, proje, framework preset, root directory, Node.js sürümü, paket yöneticisi ve Git branch'inden oluşur. Bunlardan biri değişirse başka bir cache kullanılır.
• Cache bir ay tutulur ve hangi dosyaların cache'leneceğini ayarlayamazsınız.

Bir kereliğine onsuz build için:

• Dashboard'da Redeploy deyip Use existing Build Cache kutusunu boş bırakın.
• CLI ile vercel --force.

Her build'de geri yüklemeyi atlamak için VERCEL_FORCE_NO_BUILD_CACHE ortam değişkenini 1 yapın. Başarılı build yine de sonunda yeni bir cache yükler. VERCEL_FORCE_NO_BUILD_CACHE_UPLOAD=1 tersini yapar: mevcut cache'e dokunmaz.

Tecrübem: cache temizlemek ilk değil son denenecek şey. Net bir hata mesajı olan düşmeyi nadiren açıklar ve sonraki her build'i yavaşlatır. Hata bayat durum gibi görünüyorsa, örneğin bir bağımlılık yerelde olduğundan farklı çözülüyorsa, denemeye değer. Sebep cache'teyse onsuz yeniden deploy düzeltir; onsuz da aynı şekilde düşüyorsa cache sorun değildi ve orada aramayı bırakabilirsiniz.

Özet

• Önce build'in başlayıp başlamadığına karar verin. Hatalı build logu varsa son satırdan yukarı çıkıp ilk gerçek hatayı bulun. Log yok, mesaj paneli varsa build başlamadan durdurulmuş.
• Geçen yerel build göründüğünden az şey kanıtlar. Vercel sıfırdan kurar; diff'inizde package-lock.json'a bakın ve lock dosyasının npm sürümünden farklısını kullanmayın.
• Bloklanan dağıtım eski sürümü 200 ile servis etmeye devam eder. Özel depoda commit yazarının Vercel projesine erişimi olmalı; Hobby'de bu ekip sahibi olmak demek. Git e-postası, bağlı hesapta doğrulanmış bir adresle eşleşmeli.
• Deploy'u durum koduyla değil, yeni içeriği canlıda bularak doğrulayın.
• Başarısız build cache'i hiç değiştirmez. Elemek için bir kez cache'siz yeniden deploy edin, kalıcı olarak kapatmayın.