Classify and fix Streamlit Community Cloud deployment failures

TL;DR

Don't change code until you've classified the failure from the app's logs: the app owner opens them from the "Manage app" menu (bottom-right of the deployed app). Log lines: ❗️ installer returned a non-zero exit code / ❗️ Error during processing dependencies! Please fix the error and push an update, or try restarting the app.

import streamlit as st

value = st.secrets.get("api_key")
if not value:
    st.error("Missing 'api_key' in app secrets (workspace → app ⋮ → Settings → Secrets).")
    st.stop()

When to use

You are seeing this: Match what you see against the four signatures below. Use this skill when you run into "Classify and fix Streamlit Community Cloud deployment failures".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: pandas 2.2.3. If you are on something much newer or older, the details may have shifted.

Use this when an app runs locally but fails on Streamlit Community Cloud (share.streamlit.io), or when a deployed app that used to work now shows an error page. Don't change code until you've classified the failure from the app's logs: the app owner opens them from the "Manage app" menu (bottom-right of the deployed app). Match what you see against the four signatures below.

1. The four signatures

• A. Dependency failure at build time. Log lines: ❗️ installer returned a non-zero exit code / ❗️ Error during processing dependencies! Please fix the error and push an update, or try restarting the app. The app never starts.

• B. Runtime crash after start. The app builds, then shows "Oh no. Error running app.", or the log says ❗️ Streamlit server consistently failed status checks / ❗️ Please fix the errors, push an update to the git repo, or reboot the app. The traceback in the logs names the real exception.

• C. Resource exhaustion. The app shows "This app has gone over its resource limits." Community Cloud gives each app 1 GB of RAM; exceeding it kills the app, often mid-session.

• D. Secrets/config missing. Works locally, fails on Cloud with a KeyError from st.secrets[...] or a connection error to a private service.

2. Fix A: dependency install failures

• requirements.txt is the supported path; pin versions (pandas==2.2.3) so a fresh solve can't drift. A common failure: a package that installs fine locally fails on Cloud because the local machine had a cached wheel or a system library the Cloud image lacks.

• environment.yml (conda) is a frequent trap: the conda solver can exhaust the 1 GB build memory and get OOM-killed (bash: line 3: 11 Killed ... conda env update), even for packages pip would install fine. Prefer requirements.txt; use conda only if a package truly has no pip wheel.

• Non-Python system libraries (e.g. libgl1 for OpenCV, tesseract-ocr) go in packages.txt at the repo root, one apt package name per line. They are installed with apt before pip runs.

• Set the Python version under Advanced settings at deploy time, and reproduce failures locally with that same version.

3. Fix B: runtime crashes

• Read the traceback in the logs, not the "Oh no" page. It usually names a missing file, a wrong relative path (the working directory on Cloud is the repo root; on your machine you may have run Streamlit from a subfolder), or an unhandled exception in a code path local testing never hit.

• Pushing a fix redeploys automatically. If the app looks stuck after a push, reboot from the ⋮ menu → "Reboot app".

4. Fix C: over resource limits

Rebooting clears it temporarily; the fix is using less memory:

• Don't hold the full raw dataset in memory. Downcast dtypes (object → category, float64 → float32), drop unused columns, aggregate before caching.

• Give caches a ttl so stale entries expire instead of accumulating: @st.cache_data(ttl=3600).

• Load heavy artifacts (model weights) once via @st.cache_resource, not once per session.

• If the dependency install itself gets killed, that's signature A, not C fix the environment, not the code.

5. Fix D: secrets

• Never commit .streamlit/secrets.toml, add it to .gitignore. On Cloud, paste the file's TOML contents into the "Secrets" field under Advanced settings while deploying; for an already-deployed app, go to the workspace, the app's ⋮ menu → Settings → Secrets. The app restarts and picks them up.

• Read secrets in code through indirection, and fail legibly when one is absent:

import streamlit as st

value = st.secrets.get("api_key")
if not value:
    st.error("Missing 'api_key' in app secrets (workspace → app ⋮ → Settings → Secrets).")
    st.stop()

6. Checklist

1. Open the logs (Manage app) and match the signature: dependency (A), runtime (B), resources (C), secrets (D).

2. A → pin requirements.txt, drop conda unless unavoidable, system libs in packages.txt, match the Python version.

3. B → read the traceback; check relative paths and untested code paths.

4. C → reboot is triage; shrink memory (dtypes, ttl, lazy loads) for the cure.

5. D → secrets via app settings, never committed; .gitignore the local file.

Built from Streamlit Community Cloud forum reports (dependency install failures, 'Streamlit server consistently failed status checks', 'This app has gone over its resource limits' with the 1 GB limit, conda solver OOM-kills) and the official Streamlit docs on secrets management for Community Cloud (Advanced settings Secrets field, .streamlit/secrets.toml gitignored, workspace app settings).