Troubleshooting#
Run examples/smoke_test.sh http://<host>:8000 first: it names the check that fails.
| Symptom | Cause and fix |
|---|---|
503 Model not ready | The model is still loading (up to a minute after start, longer under emulation). Wait for GET /ready to return 200. Clients should retry 503 after a few seconds. |
Container exits with code 137, or docker logs stops mid-request | Out of memory. A container peaks at about 5.5 GB: give it 8 GB (check Docker Desktop's memory limit, and --memory if you set one). Run one container per 8 GB of RAM. |
| Very slow on a Mac, warning about platform | The image is linux/amd64. On Apple Silicon it runs under emulation (add --platform linux/amd64), several times slower than on an x86 server. Fine for development, not for latency tests. |
| Slow on a server | Latency scales with cores and WITHOUTBG_MAX_INFERENCE_SIDE. Check nproc inside the container (docker exec withoutbg nproc) and any CPU limits. With several containers on one server, set WITHOUTBG_ORT_THREADS to each one's share. See Configuration and sizing. |
| Requests time out under load | One container processes one image at a time and queues the rest. Raise the client and proxy timeout to 120 s or more, and add containers for throughput. |
413 from your proxy | The proxy's body limit is below the photo size (base64 adds a third). Set 25 MB or more for the API paths. |
422 "... does not match image size" | A Smart Brush mask or matte must be exactly the photo's size after EXIF orientation. Phone photos are often stored rotated: rotate the photo by its EXIF tag before drawing the mask, or send the matte this server returned. |
422 "A matte needs a keep_mask or remove_mask" | matte is only used for edits: send it together with at least one mask. |
422 with a detail list | Request validation: output must be cutout or matte; the /base64 body needs image. |
400 Invalid image input | The body is not an image Pillow can read, or the base64 is broken (data URLs are fine). Check the file opens locally. |
| A Remove stroke removed more than expected | Edits work per object: a stroke on an object removes all of it. Use Keep strokes on the parts that must stay; where both mark a pixel, Remove wins. |
docker pull says no basic auth credentials or denied | The registry login expired (12 hours) or used the wrong credentials. Repeat step 1 of Quickstart. After your 12 months of updates, pull access ends: run the images you already copied to your own registry. |
/docs is blank | Something between you and the container strips /docs-assets/*. Allow that path in your proxy; the page needs no internet. |
Still stuck: Support lists what to send us.
This page as markdown: /pro-model-self-host/docs/troubleshooting.md. Not a customer yet? Pro Model Self-Host.