Upgrade and troubleshoot

Upgrade

Set the new tag on the Compute Lite image, then re-create the container. On Kubernetes, change the image of the Deployment.

docker compose up -d compute-lite

Running sandboxes stop. Chat sandboxes resume on the next message. Sandbox images follow your NocoDB version; to remove old ones, run docker image prune -a inside Compute Lite.

Compute Lite has nothing to back up. Its logs are JSON, one line per event.

Common problems

Problem	Cause and fix
NocoDB does not use Compute Lite.	The license has no Compute Lite add-on, or one of `NC_COMPUTE_LITE_URL`, `NC_COMPUTE_LITE_KEY` and `NC_COMPUTE_LITE_DOMAIN` is not set.
"The machine could not be woken", or scripts fail at once.	NocoDB cannot reach `NC_COMPUTE_LITE_URL`, or the keys are different. Run `curl <url>/health` from the NocoDB container.
"The compute agent at `<port>-<id>.<domain>` could not be reached."	`*.<domain>` does not resolve to Compute Lite from NocoDB, or port `8431` is blocked.
"Too many machines are running."	Increase `NC_COMPUTE_LITE_MAX_SANDBOXES`, or add capacity.
The first run is very slow, or the first chat fails.	Compute Lite is downloading an image. Pull the images before use.
`image … is built for amd64; this Docker host is arm64`	An image override points to a build for one platform. Use the published images, or build for your platform.
"the embedded Docker engine did not start"	Run Compute Lite with `--privileged`, or use host mode.
"could not install the sandbox egress rule"	The container has no iptables access. Run it with `--privileged`.
403 "not reachable from a sandbox"	The NocoDB network overlaps the sandbox range. Set `NC_COMPUTE_LITE_ADDRESS_POOL` to a free range and re-create the Compute Lite volume.
License activation fails with `fetch failed`, but the license server is reachable.	On some IPv6 networks, Node stops slow IPv4 connections. Set `NODE_OPTIONS=--network-family-autoselection-attempt-timeout=3000` on NocoDB.

When you ask for help, include the output of docker compose logs compute-lite --tail 50 (or kubectl logs deploy/nc-compute-lite --tail=50) and the NocoDB logs from the same time.