Docs menu
Troubleshooting PHP
Common build and runtime errors for PHP apps on Primcloud, with the fix for each.
On this page
Build failures show in the deployment's build log, including Composer's output and your Composer scripts'. Runtime problems, like PHP-FPM startup errors, fatal errors, and uncaught exceptions, show in the Logs tab.
Common build errors#
No composer.json found#
There's no composer.json at the root of the repo, so the build didn't recognize a PHP app.
Fix. Add a composer.json at the root. An empty {} is enough to trigger detection, though a real app will have a require section. Primcloud builds from the root of your repo. To use a manifest with another name or path, add a COMPOSER secret naming it.
No Composer lock file found#
composer.json declares dependencies in require, but there's no composer.lock alongside it. The build refuses to guess a version graph.
Fix. Run composer update locally to generate composer.lock, then commit and push:
composer update
git add composer.lock
git commit -m "Add composer.lock"
git push
If composer.lock is in .gitignore, remove it. The lockfile has to be checked in for reproducible deploys.
Failed to parse 'composer.json' or 'composer.lock'#
One of the files has a JSON syntax error, usually from a manual edit or an unresolved merge conflict.
Fix. Run composer validate locally to identify the exact line. For a botched lockfile, composer update --lock regenerates it from composer.json.
Failed to install platform dependencies#
Composer couldn't find a combination of PHP version, extensions, and package versions that satisfies every constraint in your composer.json and composer.lock.
The build log shows Composer's full explanation above the error. Look for the package or extension it couldn't place.
Fix.
- If it's a PHP version conflict (a dependency requires PHP 8.4 but you've pinned
"php": "^8.2"), bump the constraint andcomposer update. - If it's a missing extension (a dependency requires
ext-intland you haven't declared it), add it tocomposer.jsonandcomposer update. - If it's a version conflict between two dependencies, run
composer why-not <package> <version>locally to see what's blocking the resolution.
Runtime specified in 'require-dev' but not in 'require'#
require-dev names a PHP version (directly or via a dev-only dependency), but the main require doesn't. Composer can't pick a default runtime in this case even though --no-dev skips the dev packages at install time.
Fix. Add an explicit "php" entry to require in composer.json, run composer update, commit both files.
Failed to install platform dependencies: no matching PHP version#
The same error appears when your php requirement doesn't match any version the Primcloud Runtime supports. It either asks for an unsupported version (PHP 7.x, PHP 9.x) or pins an exact release that isn't available.
Fix. Bump to a version listed in Runtime versions. Loosen strict constraints ("8.4.7" becomes "^8.4") so the resolver has room to pick an available patch.
Dependency installation failed!#
Composer ran and exited non-zero. This is the catch-all for post-resolution failures: network issues, private repository auth failures, or a broken post-install-cmd.
Fix. Read the output just above the error. Common causes:
- Auth failure against a private repository. Add a
COMPOSER_AUTHsecret; see Package managers → Private packages and registries. - A
post-install-cmdscript threw an error. The command's own output is in the log. Fix the underlying issue (missing file, unset env var, failed HTTP call) and redeploy.
Common runtime errors#
App doesn't bind to $PORT#
The deployment fails while waiting for your web process to accept connections, because it isn't listening on $PORT.
Fix. Use heroku-php-apache2 or heroku-php-nginx for your web process; both listen on $PORT. A custom entrypoint, like php -S, has to read $PORT itself:
$port = getenv('PORT') ?: '8080';
Document root not found#
The build succeeds but every request returns a 404 or an nginx/Apache default page.
Fix. Check the argument after the launcher in your Procfile:
web: heroku-php-nginx public/
It must be the directory, relative to the repo root, that holds your front controller (index.php): public/ for Laravel and Symfony, web/ or public/ for Slim. Without it, your app is served from the repo root.
Fatal: Uncaught Error: Class not found#
PHP couldn't autoload a class at runtime, usually because the class isn't in the classmap generated at build time.
Fix. Add the missing PSR-4 namespace to autoload in composer.json, commit, and redeploy:
{
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}
The classmap is generated during composer install. If a Composer script generates classes, run composer dump-autoload -o as its last step.
PHP Fatal error: Uncaught Error: Call to undefined function ext_*#
Your code calls a function from an extension that isn't loaded: intl, gd, redis, imagick, and so on.
Fix. Declare the extension in composer.json, run composer update to write it into the lockfile, commit, and redeploy:
{
"require": {
"php": "^8.4",
"ext-intl": "*",
"ext-gd": "*"
}
}
See Customizing the build → Native dependencies for the supported extension set.
Request terminated after 30 seconds#
PHP-FPM stops any request still running after 30 seconds.
Fix. Move long work, like a report export or a bulk import, to a queue handled by a worker process:
web: heroku-php-nginx public/
worker: php artisan queue:work
Dispatch the work from the request and return right away. For a one-off job, such as an initial data import, run a task.
Out of memory (OOM) at build time#
Composer ran out of memory during install, which can happen with very large dependency sets.
Fix. Add a COMPOSER_MEMORY_LIMIT=-1 secret to remove Composer's memory limit, then redeploy.
Debugging tips#
- Run the build's command locally.
composer install --no-dev --optimize-autoloaderreproduces most build failures. - Check the PHP version. The build log shows the version it installed; compare it with what
composer.jsonandcomposer.lockask for. - Run diagnostics as a task.
php -mlists the loaded extensions andcomposer show -ithe installed packages.