Resolve deployment, configuration, and image-processing errors.
Confirm the account your CLI is using:
pnpm --filter @nobg/api exec wrangler whoamiCheck your account permissions and the account_id, Worker name, and binding configuration in apps/api/wrangler.jsonc. If Cloudflare rejects the Images binding, confirm the account’s Images access before retrying. See requirements and costs.
Use the API URL printed by this command:
pnpm --filter @nobg/api run deployThe health route is /api/health; background removal requires POST /api/v1/remove-background. Other paths and unsupported methods return 404. The documentation host does not serve these API routes.
Check that all quota variables are positive integers and MAX_UPLOAD_BYTES is an integer between 1 and 20971520. Use the supplied Durable Object binding and migration.
Send multipart form data with exactly one image file. The optional format field accepts png or webp. Do not manually set the multipart boundary when your client creates the form body. The route also requires a valid Cloudflare client IP. For local requests, see local testing.
The Images service could not inspect the image. Try opening and re-exporting it as JPEG, PNG, or WebP. An Images inspection error can also indicate a binding or service problem; check your Cloudflare configuration if valid files all fail.
Reduce the file size or image dimensions. The default file cap is 10 MiB and the decoded pixel cap is 25 megapixels. Multipart request overhead is also bounded. See configuration.
Use JPEG, PNG, or WebP and ensure the MIME type matches the bytes. An SVG renamed to .png is still an SVG. The output format must be png or webp.
Wait for the Retry-After interval. The default is 5 requests per UTC calendar minute per IP.
The IP has used its 20 daily image attempts, or the service has used its 10,000 monthly attempts. Honor Retry-After. Daily and monthly windows reset at midnight UTC and the start of the next UTC month. Changing IPs does not bypass the shared monthly budget.
Background segmentation is not available in the local Images implementation. Mocked tests can pass while a local upload fails during inspection or transformation. See local testing.
Check that Images is enabled for the account, the IMAGES binding exists, and the required paid access is available. If those are correct, retry with a small, valid image. Keep the X-Request-Id when investigating failures. The public health endpoint only checks liveness.
Keep the response status, JSON error code, and X-Request-Id. Use Worker logs and deployment history to check what is running. Do not include the image contents in a bug report.