It built, it started, it is red

Three logs, and they say different things

On a Space page, the top right has status and logs. There are two streams and people read the wrong one.

Build logs cover cloning, installing dependencies and constructing the image. Failures here are pip resolution conflicts, missing system packages, a Python version mismatch, or an image that got too large. The Space never starts.

Container logs are your application’s stdout and stderr after it starts. Failures here are import errors, missing environment variables, out-of-memory kills and exceptions in your handlers. The Space builds and then dies or misbehaves.

A third source is the browser console, for when the app runs fine and the page misbehaves: usually a component version mismatch after an unpinned SDK upgrade.

The five failures that cover most of it

1. Build fails on dependency resolution. Two packages want incompatible versions of a third. Pin explicitly, and pin torch first because everything else resolves around it. Reproduce locally in a clean virtual environment before pushing; the build loop on the Hub is minutes long and your local loop is seconds.

2. ModuleNotFoundError at runtime. The package is imported and not in requirements.txt. It worked locally because your environment has it from something else. A clean local virtual environment catches this every time.

3. Killed with no traceback. This is the out-of-memory signature. The container exceeded its RAM and the kernel terminated it. There is no Python exception because Python did not get to handle anything. On free CPU hardware with 16 GB, loading a 7B model at float32 does this reliably. Fix by using a smaller model, a lower dtype, quantization, or bigger hardware: in that order of preference.

4. Runs, but every request is slow. Model loading inside the handler. Covered earlier, still the most common performance bug.

5. Worked yesterday, broken today, no commits. Something unpinned moved: sdk_version, a dependency, or the model repository’s main branch. This is why the configuration lesson insists on pinning all three.

Factory reboot versus restart

Restart stops and starts the container with the existing build cache. Fast, and it fixes a hung process.

Factory reboot discards the cache and rebuilds from scratch. Slow, and it is what you need when a stale layer is the problem: a dependency that installed badly, a model file that downloaded corrupt. If a Space is failing in a way that makes no sense against the code you can read, factory reboot before you spend an hour on it.

Making failures legible to yourself

Print at startup. It costs nothing and it answers the first three questions you will have:

import sys, torch, transformers, os
print("python", sys.version)
print("torch", torch.__version__, "cuda", torch.cuda.is_available())
print("transformers", transformers.__version__)
print("HF_TOKEN set:", bool(os.environ.get("HF_TOKEN")))
print("model revision:", REVISION)

And wrap handlers so users see a sentence rather than a stack trace:

def safe(fn):
    def inner(*a, **k):
        try:
            return fn(*a, **k)
        except Exception as e:
            print("handler error:", repr(e), flush=True)   # to container logs
            raise gr.Error("Something went wrong. Try a shorter input.")
    return inner

gr.Error shows a clean message in the interface. flush=True matters: buffered stdout in a container that then dies means the log line you needed never arrived.

Before you ask for help

Spaces have a Community tab, and so do the models they use. A good report contains: what you expected, what happened, the last thirty lines of the relevant log, your requirements.txt, and the sdk_version. Most unanswered questions on the Hub are missing the log or the versions, and both are two clicks away.

Shipping: the last ten minutes

Before you tell anybody about it:

1. Open it in a private window: you will find the thing that only worked because you were logged in.
2. Open it on a phone. Gradio is responsive; your custom layout may not be.
3. Click every example.
4. Submit empty input, absurdly long input, and input in a language the model does not handle.
5. Read your own readme as a stranger. Does it say what this does, what it does badly, and whether anything is stored?

Do this now

Open the container logs of a Space you have built and read them from the top. You will find at least one warning you have never seen: almost always about a default you did not know you had accepted.