Troubleshooting

Diagnose common Docker, storage, TLS, service, session, and database problems.

Start with python3 p-bitm.py doctor, then open the issue that matches the first failing dependency. Fix root causes before restarting the complete stack.

Docker reports that the legacy builder is deprecated

P-BitM requires BuildKit through the Docker Buildx plugin. The warning, or an error such as the --chmod option requires BuildKit, means the Docker CLI is falling back to the unsupported legacy builder.

Package names depend on the installed Docker distribution. For Ubuntu’s docker.io package:

sudo apt-get update
sudo apt-get install docker-buildx docker-compose-v2

If APT cannot locate these Ubuntu packages, verify that the universe component is present in the configured Ubuntu sources.

For docker-ce, configure Docker’s official Ubuntu repository and install:

sudo apt-get update
sudo apt-get install docker-buildx-plugin docker-compose-plugin

Do not mix the two package families. In both cases, verify:

docker buildx version
docker compose version

No environment export is needed after the plugins are installed. Setting DOCKER_BUILDKIT=1 does not install or replace a missing Buildx component; if Buildx is absent, it turns the fallback warning into a build error. COMPOSE_DOCKER_CLI_BUILD has no effect in Compose v2. Do not set DOCKER_BUILDKIT=0, because that explicitly selects the legacy builder.

The CLI cannot import rich

Activate the project virtual environment and install root dependencies:

source .venv/bin/activate
python3 -m pip install -r requirements.txt

Storage directories are missing

Run setup instead of creating ad-hoc container-only paths:

python3 p-bitm.py setup
python3 p-bitm.py doctor

Setup recreates storage/ and storage/campaigns/ with mode 0700 for the selected runtime identity. Compose refuses to create a missing bind source on behalf of the container runtime. Runtime logs are available through Docker and the CLI rather than as duplicated files under storage.

Backend cannot open the database

An error such as sqlite3.OperationalError: unable to open database file normally means storage was created by a different host identity. Stop retrying the stack and inspect the numeric ownership:

stat -c '%u:%g %a %n' storage storage/p-bitm.db

Run setup again as the intended operator. When root is used, P-BitM can safely adopt entries left by root for the selected non-root runtime identity. It will not silently take over storage owned by another non-root user; move that tree aside or repair its ownership explicitly after confirming who owns the data. Then run python3 p-bitm.py doctor and restart. Do not use chmod 777; collected engagement data is private runtime state.

Frontend cannot read key.pem

Do not make the host key world-readable. Run:

python3 p-bitm.py up --build

The frontend Dockerfile copies the key with ownership for its unprivileged nginx user.

A service is unhealthy

python3 p-bitm.py status
docker compose -f server/docker-compose.yml ps
docker compose -f server/docker-compose.yml logs frontend backend traefik

Frontend startup waits for the backend healthcheck. Fix the first unhealthy dependency rather than repeatedly restarting the full stack.

Browser session is blank or slow

Check campaign and target-session status, then inspect logs:

python3 p-bitm.py campaign <campaign-id> logs --tail 200
python3 p-bitm.py campaign <campaign-id> victim <victim-id> logs --tail 200

Confirm that the selected browser image exists, the target URL is reachable through the campaign egress path, and the readiness timeout has not expired.

A required port is already in use

The dashboard requires loopback port 8443; Traefik requires public ports 80 and 443. Identify the existing listener and resolve the conflict deliberately. Do not change published ports without also reviewing dashboard URLs, routing, firewall rules, and documentation.

Doctor reports a database warning

Stop writes, create a complete storage backup, and run doctor. Do not delete the database as an initial repair step.