Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chaitu426/minibox/llms.txt

Use this file to discover all available pages before exploring further.

This page collects the most common MiniBox errors and their solutions. Each accordion entry describes the symptom, root cause, and the exact steps to resolve it.
Symptom
Error: connect ECONNREFUSED 127.0.0.1:8080
or
Get "http://127.0.0.1:8080/ping": dial tcp 127.0.0.1:8080: connect: connection refused
Causeminiboxd is not running, or it is listening on a different address/port than the CLI expects.Fix
1

Start the daemon

sudo -E miniboxd
The daemon must run as root. The -E flag preserves your environment variables (including MINIBOX_DATA_ROOT and MINIBOX_API_TOKEN).
2

Verify it is listening

minibox ping
# → pong
3

If the daemon is on a non-default port

Set MINIBOX_API in the CLI’s environment:
export MINIBOX_API="http://127.0.0.1:9090"
minibox ping
Symptom
Error: 401 Unauthorized
CauseThe daemon was started with MINIBOX_API_TOKEN set, but the CLI is either sending no token or a different one.FixExport the same token value in the CLI’s shell session:
export MINIBOX_API_TOKEN="<the-token-used-to-start-miniboxd>"
minibox ping
If you have lost the token, restart the daemon with a new one:
TOKEN="$(openssl rand -hex 32)"
MINIBOX_API_TOKEN="$TOKEN" sudo -E miniboxd &
export MINIBOX_API_TOKEN="$TOKEN"
The CLI sends the token as Authorization: Bearer <token>. The daemon also accepts it as X-API-Token: <token> for environments where the Authorization header is stripped by a proxy.
Symptom
Error: build context path is not under an allowed prefix
CauseThe directory you passed as the build context is not under any path in MINIBOX_BUILD_PREFIXES. By default the allowed roots are /home, /tmp, /var/lib/minibox, /root, /srv, /opt, and /usr/local/src.FixEither move your project into an allowed directory, or add your path to the allowed list before starting the daemon:
export MINIBOX_BUILD_PREFIXES="/home,/tmp,/projects"
sudo -E miniboxd
Then retry the build from the CLI:
minibox build -t myapp /projects/myapp
Symptom
runtime: could not unshare mount namespace: operation not permitted
CauseThe container child process failed to isolate its mount namespace. This almost always means miniboxd is not running as root, or the kernel’s user.max_user_namespaces limit is set to zero.Fix
1

Ensure the daemon runs as root

sudo -E miniboxd
2

Check user namespace limits (if root is not the issue)

cat /proc/sys/user/max_user_namespaces
# Should be > 0; common value is 14007
If it is 0, enable user namespaces:
sudo sysctl -w user.max_user_namespaces=14007
Symptom
container: Error remounting root private: ...
CauseThe mount namespace setup step failed to make the container’s root mount private before pivoting. This can happen if the host root mount is shared and the process does not have sufficient capability, or if overlayfs is not available in the kernel.Fix
  • Confirm you are running on Linux with overlayfs support: 
    grep overlay /proc/filesystems
# → nodev   overlay
  • Confirm the daemon is running as root (sudo -E miniboxd).
  • On some hardened distributions, overlayfs may be restricted. Check dmesg for relevant denial messages: 
    dmesg | grep -i overlay
SymptomA service with db_mode: true (e.g. PostgreSQL, MongoDB) starts then immediately shows exited in minibox compose ps.CauseDatabase engines often rely on specific /dev entries (e.g. /dev/urandom, /dev/shm) and kernel capabilities during initialization. MiniBox provides a minimal /dev environment, and some DB images have expectations that the current beta release does not fully satisfy.Fix
1

Check the container logs

minibox compose logs
The log output usually names the missing resource or failed syscall.
2

Confirm db_mode is enabled

services:
  db:
    image: postgres:16-alpine
    db_mode: true       # required for DB engines
    data: /var/lib/postgresql/data
3

Increase shared memory if needed

Some PostgreSQL configurations require more than the 256 MB default:
    shm_size: 512
4

Check the data directory permissions

If the volume already exists from a previous run with a different UID, the DB engine may fail to chown it. Remove the old volume:
sudo rm -rf /var/lib/minibox/volumes/<project>-db-data
minibox compose up
DB container stability is a known beta limitation. Postgres support in particular is being improved. See the README for current status.
Symptom / IntentYou want to reset MiniBox to a clean state — no containers, no images, no build cache.Steps
1

Stop all running containers

minibox compose down           # if using Compose
minibox ps -a                  # list all containers
minibox rm <id>                # remove each one
2

Remove all images

minibox images
minibox rmi <image>            # repeat for each image
3

Run system prune including build cache

minibox system prune --build-cache
4

(Nuclear option) delete the data root entirely

sudo rm -rf /var/lib/minibox
# Or, if you set a custom data root:
sudo rm -rf "$MINIBOX_DATA_ROOT"
This deletes all images, containers, volumes, and state permanently. The daemon must be stopped first.
Symptomminiboxd takes several seconds to become responsive after launch.CauseBy default the daemon indexes all blobs in DataRoot/blobs/sha256/ and brings up the minibox0 bridge at startup. A large blob store or slow disk can make this take noticeable time.FixDefer both operations until they are first needed:
export MINIBOX_INDEX_ON_STARTUP=0
export MINIBOX_BRIDGE_ON_STARTUP=0
export MINIBOX_INDEX_LAYERS=0
sudo -E miniboxd
The bridge will be created lazily when the first container with a port mapping is started. The blob index will be populated incrementally as images are built or pulled.
If the blob store has grown large over time, run minibox system prune --build-cache to remove orphaned layers and reduce startup scan time permanently.

Build docs developers (and LLMs) love

Get started for freeTalk to us