apps/docs/content/troubleshooting/kong-stops-responding-under-heavy-load-locally.mdx
When running Supabase locally with the CLI, the Kong API gateway can stop responding under heavy load. This typically happens when many parallel requests are made (for example, bulk operations against the Storage API): Kong starts terminating socket connections and logs errors about not having enough available workers.
To keep the local stack lightweight, the CLI starts Kong with a single nginx
worker process (KONG_NGINX_WORKER_PROCESSES=1). A single worker minimizes
memory usage across the ~12 containers that make up the local stack, but it
also limits how many concurrent connections Kong can handle. When the number
of in-flight requests exceeds what one worker can serve, Kong becomes
unresponsive and drops connections.
You can override the number of Kong nginx worker processes by setting the
KONG_NGINX_WORKER_PROCESSES environment variable before starting the local
stack. Set it to a specific number, or to auto to let Kong allocate one
worker per available CPU:
# Use one worker per CPU core
KONG_NGINX_WORKER_PROCESSES=auto supabase start
# Or pick a fixed number of workers
KONG_NGINX_WORKER_PROCESSES=2 supabase start
You can also export the variable so it applies to every command in your shell session:
export KONG_NGINX_WORKER_PROCESSES=auto
supabase start
Increasing the worker count lets Kong handle more parallel connections at the
cost of higher memory usage. If you don't set the variable, the CLI keeps the
default of 1 worker to minimize the local stack's memory footprint.
After changing the value, restart the stack for it to take effect:
supabase stop
KONG_NGINX_WORKER_PROCESSES=auto supabase start