# 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](/pro-model-self-host/docs/configuration). |
| 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](/pro-model-self-host/docs/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](/pro-model-self-host/docs/support) lists what to send us.
