Troubleshooting#

Run examples/smoke_test.sh http://<host>:8000 first: it names the check that fails.

SymptomCause and fix
503 Model not readyThe 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-requestOut 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 platformThe 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 serverLatency 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 loadOne 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 proxyThe 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 listRequest validation: output must be cutout or matte; the /base64 body needs image.
400 Invalid image inputThe 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 expectedEdits 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 deniedThe 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 blankSomething 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.