DeployVeraDocs

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.

Son kontrol: Markdown

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; tipleri any ile susturmayın.
  • Module not found için import yolunun harflerini dosya adıyla eşleştirin ve paketi npm 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 build 0 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.0

Node.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=22 ekleyin ve package.json engines.node alanını uyumlu tutun.
  • Alt sürüm gerekiyorsa deponun köküne nixpacks.toml ekleyip nixpkgs arşivini sabitleyin (ayrıntı: Quickstart makalesi) ya da Derleme ve çalışma ayarlarında Dockerfile yöntemine geçip FROM node:22.12-slim gibi 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_URL olarak 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.PORT değerinde ve 0.0.0.0 adresinde 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.

  • COPY yolları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 start betiğ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: EACCES veya EROFS (ö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 /tmp kullanı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.