Docs menu
Troubleshooting Python
Common build and runtime errors for Python apps on Primcloud, with the fix for each.
On this page
Build failures show in the deployment's build log. Runtime problems, like gunicorn startup errors, unhandled exceptions, and import errors, show in the Logs tab.
Common build errors#
Couldn't find any supported Python package manager files#
The build looked for requirements.txt, poetry.lock, or uv.lock at the repo root and found none.
Fix. Add one of them at the root:
- pip: commit a
requirements.txt(an empty file is fine if you have no dependencies). - Poetry: run
poetry locklocally and commitpoetry.lock. - uv: run
uv locklocally and commituv.lock(uv also requires.python-version).
Check the file is at the top level of the repo, spelled exactly (case-sensitive), and not excluded by .gitignore.
Multiple Python package manager files were found#
More than one of requirements.txt, poetry.lock, uv.lock is present at the root.
Fix. Pick one package manager and delete the others. If you're migrating from pip to Poetry or uv, drop requirements.txt in the same commit that adds the new lockfile.
Pipfile detected, but not supported#
The build sees Pipfile / Pipfile.lock at the root but doesn't have a Pipenv install path.
Fix. Migrate to pip, Poetry, or uv. Simplest option: pipenv requirements > requirements.txt and commit that instead. Longer-term: run uv init or poetry init and adopt one of the lockfile-driven managers.
The runtime.txt file isn't supported#
The build reads .python-version and doesn't read runtime.txt.
Fix. Delete runtime.txt. Create .python-version at the repo root with your major Python version:
3.14
No python- prefix, no quotes, no .txt extension.
Invalid Python version in .python-version#
The file exists but doesn't parse: bad format, multiple versions, a python- prefix, or an unrecognized version string.
Fix. Write one bare version per file, either major-only (recommended) or an exact X.Y.Z patch. Comments must start with #.
No Python version was specified (uv)#
uv builds require .python-version. It's not optional the way it is for pip and Poetry.
Fix. Run uv python pin 3.14 (adjust to your major), commit the generated .python-version, and redeploy.
The requested Python version has reached end-of-life#
The version you pinned is EOL upstream and no longer in the Primcloud Runtime.
Fix. Bump .python-version to a supported major; see Runtime versions for the list. Run your test suite locally against the new version before deploying.
The requested Python version isn't recognised#
The version you pinned doesn't map to anything the Primcloud Runtime ships: either a typo, an unreleased version, or a major beyond the current supported range.
Fix. Check against Runtime versions and set .python-version to a supported major.
Unsafe environment variable#
The build rejects a small set of environment variables that would break the install: VIRTUAL_ENV, PYTHONHOME, PIP_TARGET, PIP_PREFIX, PIP_USER, POETRY_HOME, POETRY_VIRTUALENVS_CREATE, UV_PROJECT_ENVIRONMENT, UV_PYTHON, and similar variables that control where Python or the package manager installs things. If one is set on your app, the build fails immediately with a list of the offending vars.
Fix. Remove those secrets. If you didn't set them, check that none of your build scripts sets them.
pip install / poetry sync / uv sync failed#
The package manager exited non-zero. The actual error is in the build log just above the error: a missing package, a version conflict, a native build that couldn't find a header file, and so on.
Fix. Read the package manager's error and address it:
- Version conflict: pin compatible versions in
requirements.txt/pyproject.tomland re-lock. - Missing header (
fatal error: X.h: No such file or directory): declare the corresponding-devpackage inproject.toml(see Customizing the build → Debian packages). For example,psycopg2needslibpq-dev;lxmlfrom source needslibxml2-devandlibxslt1-dev. - Missing wheel for the Python version: either upgrade the package to a version that publishes wheels for your Python, or downgrade
.python-versionto one the wheel supports.
Reproduce locally with the same command the build runs; see Package managers → Install behavior for each.
Django collectstatic failed#
collectstatic ran because Django is installed and manage.py is present, but it exited non-zero.
Fix. The Django error is in the build log. Common causes:
- Settings module can't import. A missing env var read at import time (a
DATABASE_URL,SECRET_KEY, or similar). Either provide a build-time default insettings.pyor set the variable as a secret. STATIC_ROOTnot set. SetSTATIC_ROOTinsettings.pyto a path Django can write to during the build, typicallyBASE_DIR / "staticfiles".django.contrib.staticfilesnot enabled. If your app doesn't serve static files through Django, disablecollectstaticby removingdjango.contrib.staticfilesfromINSTALLED_APPS. The build skips the step automatically when it's absent.
See Deploying Django → Framework gotchas on Primcloud for the full Django checklist.
Common runtime errors#
App doesn't bind to $PORT#
The deployment fails while waiting for your web process to accept connections.
Fix. Make sure the web command in your Procfile passes the port through:
Gunicorn:
web: gunicorn myapp.wsgi --bind 0.0.0.0:$PORT
With no --bind, Gunicorn listens on 0.0.0.0:$PORT because PORT is set on web. A --bind with another address or port, such as 127.0.0.1:8000, gets no traffic.
Uvicorn:
web: uvicorn myapp.asgi:application --host 0.0.0.0 --port $PORT
ModuleNotFoundError at startup#
Your app starts and immediately crashes with ModuleNotFoundError: No module named '<something>'.
Fix. The package isn't in the installed venv:
- Confirm the package is listed in
requirements.txt/pyproject.toml, and that the lockfile (poetry.lock/uv.lock) was regenerated after adding it. - If it's a first-party module in your repo, confirm the file is checked into git and the import path matches the directory structure.
- If it worked locally but not on Primcloud, you may have a package installed globally on your dev machine that's not in the lockfile. Install into a fresh venv locally to reproduce.
Missing shared library at runtime#
Symptom: OSError: libmagic.so.1: cannot open shared object file: No such file or directory (or similar) when the process starts.
Fix. Declare the OS package in project.toml; see Customizing the build → Debian packages. For libmagic, add libmagic1; for libpq, add libpq-dev; and so on.
App exits immediately on start#
Your logs show the process starting and then exiting with a non-zero code with no other output.
Most common causes:
- Import-time exception before logging is configured. Add a top-level
try/exceptaround your app's entrypoint that prints the exception tosys.stderrbefore re-raising, redeploy, and check logss for the traceback. - Missing required env var. If your app reads a connection string or API key at import time and raises on
None, add it as a secret and redeploy. - Gunicorn worker timeout. Long-running import-time work (loading a large model, warming a cache) can exceed Gunicorn's 30-second worker start timeout. Bump
--timeoutin thewebcommand or move the heavy work behind a lazy loader.
Debugging tips#
- Reproduce the install locally. Run the same command the build runs (see Package managers → Install behavior) against a fresh Python of the version in
.python-version. Most install failures reproduce this way. - Watch the version-resolution log line. The build log's early output prints the resolved Python version and where the requirement came from (the default or
.python-version). If the resolved version isn't what you expected, check.python-versionis at the repo root and committed. - Turn on Python's fault handler.
PYTHONFAULTHANDLER=1(set as a secret) makes Python print a traceback on segfaults, which helps with crashes in native extensions.