# 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.

Last reviewed: 2026-11-12

## 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.

Sources: https://api.deployvera.com/api/plans · https://deployvera.com/docker · https://deployvera.com/help
