# Troubleshooting

> What to do when a deployment fails, common problems and the list of error summaries Turguz recognises.

When Turguz cannot complete an operation, it tries to tell you what happened, why and what you need to do. This page gathers where to find those messages, the most common problems and the error summaries Turguz recognises.

## If a deployment fails

**Read the summary**

On the environment's **Dağıtımlar** (Deployments) tab, a deployment in the «Hata» (Error) state comes with a short summary: what happened, why and what to do. If the summary describes a recognised situation, a «Belgede oku» (Read in the docs) link appears next to it and takes you to that situation in the [error summaries](#hata-ozetleri) list below. The same link is also on the deployment screen of the mobile app.
**Go to the suggested place**

Next to the summary there is often a button that takes you to the right place: «Yeniden derle» (Rebuild), «Veritabanı ayarlarına git» (Go to database settings) or «Ortam değişkenlerine git» (Go to environment variables).
**Check the log**

For details, read the «Derleme günlüğü» (Build log) and «Canlı günlük» (Live log) output on the **Günlükler** (Logs) tab.
**Fix it and try again**

Fix the project and push it again, or use «Yeniden derle» (Rebuild). If the build fails, the live version keeps running.

## The site does not open

- Your application must listen on the port in the `PORT` variable and on the `0.0.0.0` address: [Port and address](/docs/en/proje-yayinlama#port-ve-adres).
- The environment may have been stopped; start it with «Başlat» (Start) in the environment's header.
- The site may be open only to certain addresses: [Internet access](/docs/en/internet-erisimi).
- If a new version is going live, wait a few seconds until the application starts.
- If visitors see the "The site isn't responding right now" page, your application cannot handle requests or is itself returning a 502 or 503 response; check the «Canlı günlük» (Live log) output on the **Günlükler** (Logs) tab. Details: [While the site is starting or unavailable](/docs/en/proje-yayinlama#site-acilirken-ve-kapaliyken).

## The application cannot reach an external service

Environments and servers are closed to the internet by default; the log shows only timeouts. Request access: [Internet access](/docs/en/internet-erisimi).

## The quota is not enough

An action the quota cannot cover is not carried out. What to do: [If the quota is not enough](/docs/en/kota-ve-kullanim#kota-yetmezse).

## SSH connection is refused

A server accepts sign-in with one of the keys written to it or with the password you gave when creating it. If you added your key to the panel, look at the **SSH anahtarlarım** (My SSH keys) section on the Settings page: if your key does not reach a server on its own, that server and what to do are listed there. If no route works, use the console in your browser. Details: [Connecting](/docs/en/sanal-sunucu#baglanmak).

## What your project needs

To see problems before going live, check the environment's **Hazırlık** (Readiness) section: [Readiness report](/docs/en/proje-yayinlama#hazirlik-raporu).

## Asking for help

When you pass a problem you cannot solve to your platform admin, include the name of the environment or the server, when the problem happened and the message in the panel.

## Error summaries

The list below shows the situations Turguz recognises in a failed deployment, grouped by category. For some situations the summary is written for your project; for those, only the title is listed.

### Repository layout

Turguz could not work out where and how to find the application in your repository: the application folder, a submodule or another platform's configuration file. The summary says what was found. Set the application folder in the environment's **Ayarlar** (Settings) › **Derleme ve çalıştırma** (Build and run) section, in the «Uygulama klasörü» (App folder) field.

#### The app needs a MySQL database

#### A PHP site can't be served from the project root

#### The PHP project has no public/index.php

#### The pip in the Dockerfile can't read the package index

#### A file the Dockerfile runs has no execute permission

#### A step in the Dockerfile failed

#### The repository uses git submodules

#### References to files outside the application folder

### Build

Turguz stopped while building the project. Check that the project's language was recognised and that the application folder is correct; if needed, set the build command in the environment's **Ayarlar** (Settings) › **Derleme ve çalıştırma** (Build and run) section. After fixing it, use «Yeniden derle» (Rebuild).

#### The build exceeded its time limit

#### The build's working space filled up

#### A Composer script failed during the build

#### The project file doesn't declare its target framework

#### The build also updates the database

#### The build queries the code's git history

#### SvelteKit validates environment variables during the build

#### The Go main program is not at the root of the application folder

#### The build calls a program that is not in the build environment

#### The Clojure project has no build path defined

#### The build validates the application's settings

#### Packages of the projects in subfolders are not installed

#### The program called by the build command was not found

#### A program called by the build script is not in the build environment

#### The build script could not find a development package

#### The Next.js configuration has an option that is valid only in Turbopack

#### Next.js is built with webpack

The build stopped: your build script selects Turbopack (`next build --turbopack`), and Turbopack does not work in this build environment. Change the script to `"build": "next build --webpack"` or remove the `--turbopack` flag. Do NOT add the `turbopack.root` setting to `next.config`, and REMOVE it if it is there: the application cannot find external packages while running.

#### Next.js is built in production mode

The build stopped: it ran with `NODE_ENV=development` and crashed while pre-rendering the pages. If `NODE_ENV` is defined in your environment variables, remove it or set it to `production`; Turguz does not touch your value. If it is not defined, write `"build": "NODE_ENV=production next build"` in package.json; on Next.js 16, add `--webpack` at the end.

#### Node ran out of memory

#### An old build tool does not work with a newer Node

#### The code has a TypeScript type error

#### The browser could not be added during the build

#### Django could not collect the static files

#### The folder has more than one .NET project

The .NET build stopped: the application folder has more than one project or solution file, and Turguz could not choose which one to build. Select the folder of the project to build with `BP_DOTNET_PROJECT_PATH` in the environment variables (for example `src/App`). If two application projects are in the same folder, move one of them to a separate folder.

#### The build tried to connect to the database

The build stopped: it tried to connect to the database, which is available only while the application is running. Take the pages that fetch data out of the build (make them dynamic).

#### The project's language could not be recognised

The build did not start: the project's language could not be recognised; the application folder has no file like `package.json` and no `index.html`. If the application is in a subfolder, select it with Settings › App folder. Turguz can offer its own Dockerfile for some languages: see the Readiness card.

### Packages and dependencies

Dependencies could not be installed. Check that your lock file is in the repository and up to date. If you suspect the cache, have the dependencies installed from scratch when you rebuild.

#### The package is not in this site's package mirror

#### The package mirror was not added to this build

#### The project's go.sum is missing or out of date

#### The project's go.mod doesn't list the module of an imported package

#### The repository has no composer.lock file

#### The app would fetch its own workspace packages from outside

#### The lock file contains a malicious package

#### The lock file could not be read, so its packages were not checked

#### A required PHP extension isn't in the build environment

#### A gem that became a separate package in Ruby 3.4 couldn't be loaded

#### The package list's validity period has expired

Build failed: `apt-get update` in the Dockerfile stopped because the package list's validity period has expired. This server has no internet access; the package list is refreshed when the platform is updated. If the `FROM` line uses a base Turguz recognizes (node, python, php, debian …) this resolves itself; if you use another base, write `apt-get -o Acquire::Check-Valid-Until=false update` in your Dockerfile.

#### The project is installed with pnpm

The `pnpm` command did not run: pnpm was not installed for this project. Turguz installs pnpm only when `pnpm-lock.yaml` is the only lock file or when the `packageManager` field says pnpm. Remove the other lock files (`package-lock.json`, `yarn.lock`) or add `"packageManager": "pnpm@<version>"` to package.json.

#### The application folder is inside a pnpm workspace

Dependencies could not be installed: the project depends on another package in its pnpm workspace (`workspace:`), and that package is outside the selected folder. Make the workspace root the application folder. Set the build command to `pnpm --filter <package> build` and the start command to `pnpm --filter <package> start`.

#### The project is installed with Yarn 2 or newer

#### The project is installed with bun

#### The lock file does not match package.json

#### Packages require conflicting versions

#### A dependency is installed from a git repository

#### The image library sharp could not be loaded

#### Generating the Prisma client

#### Prisma's config file needs a variable during the build

#### Missing Node module

The application could not find a Node module: the package was not installed or is not in package.json. Add the missing package to the `dependencies` section of package.json.

#### The project's own Python module was not found

#### Missing Python package

#### Dependency installation (npm) failed

Dependencies could not be installed: npm reported an error. See the npm line in the details and fix the package or version in package.json.

### Language version

A problem with the language version the project asks for. The summary says where the version is read from and what needs to change.

#### The requested PHP version isn't in the build environment

#### Dependencies require a different PHP version

#### The requested Java version isn't in the build environment

#### The requested Ruby version isn't in the build environment

#### The .NET SDK requirement is adapted to the build environment

#### The requested .NET SDK version is not in the build environment

#### The Node version the project asks for is not in the build environment

#### The Node version is requested without an upper bound

#### The Python version is chosen from the project

### Start-up

The build finished but the application could not be started. Check the start command in the environment's **Ayarlar** (Settings) › **Derleme ve çalıştırma** (Build and run) section.

#### The start script is a development server

#### The start command Turguz chose did not open a server

#### How to start the application could not be determined

#### The start command is a file name with no interpreter

#### The start command was not found

#### The nginx started by the application did not come up

### While running

The application started but stopped while running: wrong port, not enough memory, a file it cannot write or a missing library. Make sure the application listens on the `PORT` variable and the `0.0.0.0` address ([Port and address](/docs/en/proje-yayinlama#port-ve-adres)); if memory is not enough, increase the [environment size](/docs/en/ortamlar#ortam-boyu).

#### The app couldn't write to a folder

#### The app listens on a different port

#### The app listens only on an address reachable from inside itself

#### The app did not open its port

#### The start file cannot be executed

#### An Erlang application could not allocate memory for its connection table at startup

#### Not enough memory

The application stopped: it ran out of memory and exceeded the environment's memory limit. Increase the environment's size or reduce the application's memory use.

#### The Play server starts without a PID file on the environment's port

#### JVM memory is calculated at startup from the container's size

#### The browser's sandbox did not start

#### There is no browser in the runtime environment

#### The browser stopped while starting

#### The application's files did not fit on the temporary disk

#### The temporary disk could not be prepared

The application did not open: its files could not be copied to the temporary disk; the reason is in the details below. Redeploy; if it persists, let the platform admin know.

#### The persistent disk could not be prepared

The release stopped and the running version did not change: the persistent disk could not be prepared because the platform's preparation tool could not be loaded. Let the platform admin know.

#### The persistent folder's path contains a symbolic link

#### The path made persistent is a file in the built application

#### The persistent folder's parent folder is not in the built application

#### The persistent disk is full

The application could not write: the persistent disk is full. Enlarge the persistent disk or delete unneeded files on it.

#### The application could not write to the persistent disk

The application could not write to the persistent disk: permission denied. If the application switches its user at startup, run it as the same user from the start; otherwise contact the platform admin.

#### The application's temporary space is full

The application was stopped and the files it wrote were deleted: its temporary space filled up. Open a persistent disk for files that must be kept; clean up temporary files or enlarge the application's temporary disk.

#### The application tried to write to a read-only path

#### The temporary disk is full

The application could not write: its temporary disk is full. Enlarge the application's temporary disk or reduce the files it writes.

#### A system library is missing from the runtime environment

#### Port already in use

The application did not open: the port it wants to listen on is already in use. Let a single process open the port; start the application so that it listens on the port in the `PORT` variable.

#### Insufficient file permission

The application could not write to a file or folder: permission denied. See the path in the details; have the application write its files under `/tmp` or to a persistent disk.

#### File or folder not found

The application could not find a file or folder it expects. See the path in the details; add the file to the repository or fix the path.

#### A command calls a package script the application does not have

### Static site

The static site's build output could not be found or its folder is wrong. The summary says which folder was expected.

#### The build output to serve could not be found

#### The static folder you set manually cannot be used (missing, no index.html, or outside the repository)

#### A tool file at the root of the static site may cause another language to be selected

The site did not open: Node is not in the built application; the project was built with another language (for example Ruby, because of the `Rakefile` at the root). Rebuild; Turguz now pins the build to Node. If you wrote the start command yourself, write one that matches the project's language.

### Databases and side services

The application could not connect to the database or a side service. Check the environment's **Veritabanı** (Database) tab ([Databases](/docs/en/veritabani)).

#### The build couldn't reach the database; it's closed to builds

The build couldn't reach the database: this environment's database is closed to builds. If your pages are generated from the database during the build, turn on «Derlemede veritabanı» (Database during build) under Settings › Build and run, and build again.

#### The build couldn't find a table it reads in the database

#### The build tried to write to the database

#### The build exceeded the database connection limit set aside for builds

The build stopped and the new version was not published: the build opened more database connections than it was given. Build again. If it happens again, remove the `experimental.cpus` setting from your `next.config` file, or the setting in your code that enlarges the database connection pool; if there is no such setting, connect the environment to a larger database server.

#### The application expects the database address in JDBC format

#### The application expects the database address in async driver format

#### The application wants separate databases for its extra connections

#### Ecto migrations run inside the application and the connection share is too small

#### An encrypted connection to the database was required

#### The database connection limit was reached

#### The database file could not be opened

The application could not open its SQLite database file: the file's folder does not exist or cannot be written to. Open a persistent disk and point the file to a path under it: `/data/db.sqlite3`.

#### The application picks the database type from a variable

#### The connection address is a name left over from Compose

#### The database extension the application needs is not available on the managed database

### Internet and external services

The application or the build tried to reach the internet. Environments cannot reach the internet by default; if needed, request [internet access](/docs/en/internet-erisimi).

#### The font could not be downloaded from Google during the build

#### An address on the internet could not be reached

#### The application could not connect to a service

The application could not connect to a service: the database or API does not exist in this environment, or its address is wrong. Check the variable that provides the address; if it is a database, connect one to the environment.

### Variables and settings

A missing or wrong environment variable or setting ([Variables](/docs/en/ortamlar#degiskenler)).

#### The application couldn't find a variable at startup

#### Django does not respond to the site's address

### Platform

The problem is not in your project but in a part of the platform. Try again shortly; if it persists, let your platform admin know.

#### An unexpected error left the operation unfinished

An unexpected error occurred and the operation was left unfinished — try again.

#### No build slot became available

#### The package mirror is not responding

Dependencies could not be installed: the package mirror is not responding and this site has no internet. Deploy again in a little while; if it persists, let your platform admin know.

#### The deployment was left unfinished and the platform closed it

#### The built version could not be saved

#### Build preparation was left unfinished

#### An external repository hit its request limit

#### The source code could not be transferred to the build environment

The source code could not be transferred to the build environment: there was a temporary problem in the platform's internal network, unrelated to your code. Upload the same file again or redeploy; if it persists, let the platform admin know.

#### The platform's build environment is incomplete

The build did not start: the platform's build environment is incomplete, unrelated to your code. The admin has been notified; redeploy once it is fixed.

#### PHP builds aren't available on this installation

#### The build was stopped because it sent too much data out

#### Repository access for the source code could not be renewed or was denied

#### The code repository could not be reached

The build did not start: the code repository could not be reached. Redeploy; if it persists, check the project's repository connection or let the platform admin know.

#### Network preparation did not complete; the application was not started

The application did not start: the platform's network preparation did not complete. Redeploy; if it persists, let the platform admin know.

#### The temporary disk could not be attached

The release stopped and the running version did not change: the application's temporary disk could not be attached. Let the platform admin know; the cause is disk space or a storage setting.

#### The database user name starts with a reserved prefix