TEKNİK REFERANS
Build hataları ve çözümleri
Sık görülen build hataları: günlükte nasıl görünür, neden olur, DeployVera'da nasıl çözülür ve nasıl doğrulanır.
Nasıl okunur
Build başarısız olduğunda panelde derleme günlüğünü açın ve ilk gerçek hata satırını bulun; sondaki exit code: 1 yalnızca özettir. Aşağıdaki başlıklar en sık karşılaşılandan başlar. Günlük örnekleri genel biçimdir, kendi günlüğünüzde adlar farklı olacaktır.
Derleme hatası (compile, özellikle Next.js)
Günlükte görünümü: Type error: ..., Failed to compile. veya process "npm run build" did not complete successfully: exit code: 1.
Nedeni: next build TypeScript ve ESLint hatalarında durur; yerel npm run dev bunları göstermeyebilir. Ayrıca Linux'ta büyük/küçük harfe duyarlı import yolları (./UserCard ile ./usercard) ve package.json'da olmayan paketler derlemeyi bozar.
- Yerelde temiz bir klonda
npm ci && npm run buildçalıştırın ve çıkan hataları düzeltin; tiplerianyile susturmayın. Module not foundiçin import yolunun harflerini dosya adıyla eşleştirin ve paketinpm install <paket>ile ekleyin.- Derleme anında gereken değişkenleri (ör.
NEXT_PUBLIC_*) Ortam değişkenleri bölümüne ekleyin; bu değerler derlemede gömülür, değiştirince yeniden derleyin. - Değişikliği push edip yeniden dağıtın.
- Doğrulama: yerelde
npm run build0 koduyla biter ve panelde yeni build 'Yayında' olur.
İpucu: Next.js
Next.js uygulamalarında derleme hatalarının çoğu şu dördüyle önlenir: next.config içinde output: 'standalone'; panelde Port ve ortam değişkeni PORT=3000; HOSTNAME=0.0.0.0; ve push etmeden önce yerelde npm run build ile TypeScript hatalarının düzeltilmesi.
// next.config.ts
export default { output: 'standalone' };
// Ortam değişkenleri
// PORT=3000
// HOSTNAME=0.0.0.0Node.js sürüm uyumsuzluğu
Günlükte görünümü: Unsupported engine, EBADENGINE veya Node.js v22.11.0 is not supported.
Nedeni: bir bağımlılık veya araç daha yeni Node.js ister; otomatik (Nixpacks) derlemenin varsayılan sürümü yetmez.
- Ortam değişkenlerine
NIXPACKS_NODE_VERSION=22ekleyin ve package.jsonengines.nodealanını uyumlu tutun. - Alt sürüm gerekiyorsa deponun köküne
nixpacks.tomlekleyip nixpkgs arşivini sabitleyin (ayrıntı: Quickstart makalesi) ya da Derleme ve çalışma ayarlarında Dockerfile yöntemine geçipFROM node:22.12-slimgibi kesin bir imaj kullanın. - Doğrulama: yeniden dağıtımda engine hatası görünmez.
Veritabanına bağlanılamıyor
Günlükte görünümü: P1001: Can't reach database server, ECONNREFUSED veya başlangıçta prisma migrate deploy hatası.
Nedeni: DATABASE_URL tanımlı değil ya da yanlış; veritabanı aynı hizmette oluşturulmamış.
- Hizmete yönetilen bir veritabanı ekleyin; aynı hizmetteki uygulama ve veritabanı özel ağda erişir.
- Bağlantı adresini Ortam değişkenleri bölümüne
DATABASE_URLolarak ekleyin. - Migration'ı başlangıç komutunda çalıştırıyorsanız hata kalıcıysa komutu ayırın.
- Doğrulama: başlangıç günlüğünde migration tamamlanır ve konteyner sağlıklı olur.
Konteyner sağlıklı değil (port)
Günlükte görünümü: New container is not healthy, rolling back to the old container veya EADDRINUSE.
Nedeni: uygulama 0.0.0.0:$PORT üzerinde dinlemiyor; yalnız localhost veya sabit bir port kullanıyor, ya da panelde Port alanı yanlış.
- Uygulamayı
process.env.PORTdeğerinde ve0.0.0.0adresinde dinleyecek şekilde değiştirin. - Panelde Port alanını uygulamanın portuyla eşleştirin.
- Doğrulama: yeni sürüm sağlıklı olur ve eski sürüme geri dönülmez.
Yapılandırma hatası (Dockerfile, dal, ortam değişkeni)
Günlükte görünümü: failed to compute cache key: "/dosya": not found, Remote branch ... not found veya Missing required environment variable.
Nedeni: Dockerfile'daki COPY depoda olmayan bir dosyaya bakıyor, seçili dal yok ya da zorunlu değişken tanımsız.
COPYyollarını depo köküne göre kontrol edin; dosyanın commit edildiğini ve.dockerignore'da olmadığını doğrulayın.- Derleme ve çalışma ayarlarında dalı gerçek dal adıyla eşleştirin.
- Günlükte adı geçen değişkenleri Ortam değişkenleri bölümüne ekleyin.
- Doğrulama: ilgili hata satırı günlükten kalkar.
Başlatma komutu yok / süreç hemen çıkıyor
Günlükte görünümü: Missing script: "start", No start command could be found veya exit code=0 ile yeniden başlayan konteyner.
Nedeni: package.json'da start betiği yok, Dockerfile'da CMD yok ya da komut çalışıp hemen bitiyor.
- package.json'a sunucuyu sürekli çalıştıran bir
startbetiği ekleyin. - Dockerfile kullanıyorsanız sona
CMD [...]ekleyin. - Derleme ve çalışma ayarlarındaki başlatma komutunun boş veya yanlış olmadığını kontrol edin.
- Doğrulama: konteyner çalışır durumda kalır ve günlükte sunucunun dinlediği satır görünür.
Depoya erişilemiyor
Günlükte görünümü: Authentication failed, Repository not found veya Permission denied (publickey).
Nedeni: Git bağlantısının yetkisi kalktı, depo silindi veya özel yapıldı.
- Git hesabını panelde yeniden yetkilendirin.
- Depo adını ve dalı kontrol edin; özel depoda hesabın okuma yetkisi olmalıdır.
- Doğrulama: günlüğün ilk adımında depo hatasız çekilir.
Diğer yaygın hatalar
- Yerel (native) bağımlılık:
apt-get install ... did not complete successfully. Paket adını doğrulayın, karmaşık sistem bağımlılıkları için Dockerfile yöntemini kullanın. - DNS:
getaddrinfo EAI_AGAIN/ENOTFOUND <ana bilgisayar>. Ana bilgisayar adını ve ortam değişkenlerindeki adresleri kontrol edin. - Yazma izni:
EACCESveyaEROFS(ör./data). Dizini uygulama kullanıcısına verin; kalıcı olması gereken dosyalar için volume bağlayın, geçici dosyalar için/tmpkullanın.
Platform kaynaklı hatalar
Bazı hatalar sizin kodunuzdan değil platformdan gelir: iç Git proxy'sinden 504 veya Git ana bilgisayarına bağlanılamaması ve fatal: early EOF gibi geçici aktarım kopmaları.
Ne yapılır: birkaç dakika bekleyip yeniden dağıtın; kodda veya ayarlarda değişiklik yapmayın. Tekrar ederse destek bileti açın ve build kimliğini ekleyin.
Derlemeyi hızlandırma
Derlemeler yavaşsa önbelleğin nasıl çalıştığını, Dockerfile katman sırasını ve paket önbelleği bağlama noktalarını /docs/tr/faster-builds makalesinde bulabilirsiniz.