{"course":{"slug":"hugging-face","title":"Hugging Face, End to End","url":"https://addaly.com/learn/hugging-face","level":"intermediate","track":"create"},"lesson":{"slug":"debugging-a-space","title":"It built, it started, it is red","url":"https://addaly.com/learn/hugging-face/debugging-a-space","position":37,"of":75,"minutes":8,"answer":"Build logs and container logs describe different phases and most confusion comes from reading the wrong one, while a container killed with no traceback is the out-of-memory signature.","keyIdea":"Build logs and container logs describe different phases and most confusion comes from reading the wrong one, while a container killed with no traceback is the out-of-memory signature, and a factory reboot rather than a restart is the fix when the code cannot explain the failure."},"body":{"format":"markdown","text":"## Three logs, and they say different things\n\nOn a Space page, the top right has status and logs. There are two streams and people read the wrong one.\n\n**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.\n\n**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.\n\nA 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.\n\n> Figure: Two log streams, and what each can tell you. A two by two grid, rows Build logs and Container logs, columns Which phase and Typical failure: Build logs and Which phase: Build; Build logs and Typical failure: Pip conflict; Container logs and Which phase: Runtime; Container logs and Typical failure: OOM kill. Most confusion here is reading the wrong stream. A build failure means the Space never started; a container failure means it started and then died. The bottom right cell is the one worth memorising: no Python traceback at all is the out-of-memory signature, because Python never got to handle anything.\n\n## The five failures that cover most of it\n\n**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.\n\n**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.\n\n**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.\n\n**4. Runs, but every request is slow.** Model loading inside the handler. Covered earlier, still the most common performance bug.\n\n**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.\n\n## Factory reboot versus restart\n\n**Restart** stops and starts the container with the existing build cache. Fast, and it fixes a hung process.\n\n**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.\n\n## Making failures legible to yourself\n\nPrint at startup. It costs nothing and it answers the first three questions you will have:\n\n```python\nimport sys, torch, transformers, os\nprint(\"python\", sys.version)\nprint(\"torch\", torch.__version__, \"cuda\", torch.cuda.is_available())\nprint(\"transformers\", transformers.__version__)\nprint(\"HF_TOKEN set:\", bool(os.environ.get(\"HF_TOKEN\")))\nprint(\"model revision:\", REVISION)\n```\n\nAnd wrap handlers so users see a sentence rather than a stack trace:\n\n```python\ndef safe(fn):\n    def inner(*a, **k):\n        try:\n            return fn(*a, **k)\n        except Exception as e:\n            print(\"handler error:\", repr(e), flush=True)   # to container logs\n            raise gr.Error(\"Something went wrong. Try a shorter input.\")\n    return inner\n```\n\n`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.\n\n## Before you ask for help\n\nSpaces 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.\n\n## Shipping: the last ten minutes\n\nBefore you tell anybody about it:\n\n1. Open it in a private window: you will find the thing that only worked because you were logged in.\n2. Open it on a phone. Gradio is responsive; your custom layout may not be.\n3. Click every example.\n4. Submit empty input, absurdly long input, and input in a language the model does not handle.\n5. Read your own readme as a stranger. Does it say what this does, what it does badly, and whether anything is stored?\n\n## Do this now\n\nOpen 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."},"check":{"question":"A Space dies a few seconds after starting, with no Python traceback in the container logs. What does that pattern indicate?","options":[{"text":"A dependency failed to install, so the application never reached its first import.","correct":false,"tempting":"An install failure appears in build logs and prevents the container from starting at all."},{"text":"The process was killed for exceeding memory, so Python never got the chance to raise anything.","correct":true},{"text":"An exception was raised inside a handler, and Gradio swallowed it to keep the interface responsive.","correct":false,"tempting":"Handler exceptions surface in the UI and the logs, and do not terminate the container."},{"text":"The sleep timer triggered immediately because the Space received no traffic after starting.","correct":false,"tempting":"Sleep stops a Space cleanly after an idle period rather than seconds after boot."}]},"prev":{"slug":"calling-a-space-as-an-api","title":"Every Space is an API you can call","url":"https://addaly.com/learn/hugging-face/calling-a-space-as-an-api"},"next":{"slug":"datasets-without-downloading","title":"Do not download the dataset","url":"https://addaly.com/learn/hugging-face/datasets-without-downloading"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Exam keys checked blind by a second model: 3,665 of 3,666 agreed. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'It built, it started, it is red', in Hugging Face, End to End. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/hugging-face/debugging-a-space (Accessed: 13 October 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"It built, it started, it is red","courseTitle":"Hugging Face, End to End","module":{"index":4,"slug":"spaces-and-shipping-something","title":"Spaces: putting something in front of people"},"answer":null,"keyIdea":"Build logs and container logs describe different phases and most confusion comes from reading the wrong one, while a container killed with no traceback is the out-of-memory signature, and a factory reboot rather than a restart is the fix when the code cannot explain the failure.","hero":{"kind":"figure","figure":{"t":"figure","label":"Figure","figure":{"cols":["Which phase","Typical failure"],"rows":["Build logs","Container logs"],"type":"matrix","cells":[["Build","Pip conflict"],["Runtime","OOM kill"]],"title":"Two log streams, and what each can tell you","caption":"Most confusion here is reading the wrong stream. A build failure means the Space never started; a container failure means it started and then died. The bottom right cell is the one worth memorising: no Python traceback at all is the out-of-memory signature, because Python never got to handle anything.","cellLabels":[["Cloning and install","Version resolution"],["Your app’s own output","No Python traceback"]]},"alt":"Figure: Two log streams, and what each can tell you. A two by two grid, rows Build logs and Container logs, columns Which phase and Typical failure: Build logs and Which phase: Build; Build logs and Typical failure: Pip conflict; Container logs and Which phase: Runtime; Container logs and Typical failure: OOM kill. Most confusion here is reading the wrong stream. A build failure means the Space never started; a container failure means it started and then died. The bottom right cell is the one worth memorising: no Python traceback at all is the out-of-memory signature, because Python never got to handle anything."}},"blocks":[{"t":"h2","id":"three-logs-and-they-say-different-things","runs":[{"text":"Three logs, and they say different things"}]},{"t":"p","runs":[{"text":"On a Space page, the top right has status and logs. There are two streams and people read the wrong one."}]},{"t":"p","runs":[{"text":"Build logs","b":true},{"text":" 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."}]},{"t":"p","runs":[{"text":"Container logs","b":true},{"text":" 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."}]},{"t":"p","runs":[{"text":"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."}]},{"t":"h2","id":"the-five-failures-that-cover-most-of-it","runs":[{"text":"The five failures that cover most of it"}]},{"t":"p","runs":[{"text":"1. Build fails on dependency resolution.","b":true},{"text":" Two packages want incompatible versions of a third. Pin explicitly, and pin "},{"text":"torch","code":true},{"text":" 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."}]},{"t":"p","runs":[{"text":"2. ","b":true},{"text":"ModuleNotFoundError","b":true,"code":true},{"text":" at runtime.","b":true},{"text":" The package is imported and not in "},{"text":"requirements.txt","code":true},{"text":". It worked locally because your environment has it from something else. A clean local virtual environment catches this every time."}]},{"t":"p","runs":[{"text":"3. Killed with no traceback.","b":true},{"text":" 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."}]},{"t":"p","runs":[{"text":"4. Runs, but every request is slow.","b":true},{"text":" Model loading inside the handler. Covered earlier, still the most common performance bug."}]},{"t":"p","runs":[{"text":"5. Worked yesterday, broken today, no commits.","b":true},{"text":" Something unpinned moved: "},{"text":"sdk_version","code":true},{"text":", a dependency, or the model repository’s "},{"text":"main","code":true},{"text":" branch. This is why the configuration lesson insists on pinning all three."}]},{"t":"h2","id":"factory-reboot-versus-restart","runs":[{"text":"Factory reboot versus restart"}]},{"t":"p","runs":[{"text":"Restart","b":true},{"text":" stops and starts the container with the existing build cache. Fast, and it fixes a hung process."}]},{"t":"p","runs":[{"text":"Factory reboot","b":true},{"text":" 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."}]},{"t":"h2","id":"making-failures-legible-to-yourself","runs":[{"text":"Making failures legible to yourself"}]},{"t":"p","runs":[{"text":"Print at startup. It costs nothing and it answers the first three questions you will have:"}]},{"t":"code","lang":"python","label":"Python","text":"import sys, torch, transformers, os\nprint(\"python\", sys.version)\nprint(\"torch\", torch.__version__, \"cuda\", torch.cuda.is_available())\nprint(\"transformers\", transformers.__version__)\nprint(\"HF_TOKEN set:\", bool(os.environ.get(\"HF_TOKEN\")))\nprint(\"model revision:\", REVISION)"},{"t":"p","runs":[{"text":"And wrap handlers so users see a sentence rather than a stack trace:"}]},{"t":"code","lang":"python","label":"Python","text":"def safe(fn):\n    def inner(*a, **k):\n        try:\n            return fn(*a, **k)\n        except Exception as e:\n            print(\"handler error:\", repr(e), flush=True)   # to container logs\n            raise gr.Error(\"Something went wrong. Try a shorter input.\")\n    return inner"},{"t":"p","runs":[{"text":"gr.Error","code":true},{"text":" shows a clean message in the interface. "},{"text":"flush=True","code":true},{"text":" matters: buffered stdout in a container that then dies means the log line you needed never arrived."}]},{"t":"h2","id":"before-you-ask-for-help","runs":[{"text":"Before you ask for help"}]},{"t":"p","runs":[{"text":"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 "},{"text":"requirements.txt","code":true},{"text":", and the "},{"text":"sdk_version","code":true},{"text":". Most unanswered questions on the Hub are missing the log or the versions, and both are two clicks away."}]},{"t":"h2","id":"shipping-the-last-ten-minutes","runs":[{"text":"Shipping: the last ten minutes"}]},{"t":"p","runs":[{"text":"Before you tell anybody about it:"}]},{"t":"ol","start":1,"items":[[{"text":"Open it in a private window: you will find the thing that only worked because you were logged in."}],[{"text":"Open it on a phone. Gradio is responsive; your custom layout may not be."}],[{"text":"Click every example."}],[{"text":"Submit empty input, absurdly long input, and input in a language the model does not handle."}],[{"text":"Read your own readme as a stranger. Does it say what this does, what it does badly, and whether anything is stored?"}]]},{"t":"h2","id":"do-this-now","runs":[{"text":"Do this now"}],"role":"try"},{"t":"p","runs":[{"text":"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."}]}],"check":{"question":[{"text":"A Space dies a few seconds after starting, with no Python traceback in the container logs. What does that pattern indicate?"}],"options":[{"text":[{"text":"A dependency failed to install, so the application never reached its first import."}],"correct":false,"tempting":[{"text":"An install failure appears in build logs and prevents the container from starting at all."}]},{"text":[{"text":"The process was killed for exceeding memory, so Python never got the chance to raise anything."}],"correct":true,"tempting":null},{"text":[{"text":"An exception was raised inside a handler, and Gradio swallowed it to keep the interface responsive."}],"correct":false,"tempting":[{"text":"Handler exceptions surface in the UI and the logs, and do not terminate the container."}]},{"text":[{"text":"The sleep timer triggered immediately because the Space received no traffic after starting."}],"correct":false,"tempting":[{"text":"Sleep stops a Space cleanly after an idle period rather than seconds after boot."}]}],"order":[0,3,1,2],"why":null},"prev":{"slug":"calling-a-space-as-an-api","title":"Every Space is an API you can call","minutes":8},"next":{"slug":"datasets-without-downloading","title":"Do not download the dataset","minutes":9}}}