> ## Documentation Index
> Fetch the complete documentation index at: https://p-bitm-2269ecee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<AccordionGroup>
  <Accordion title="Docker reports that the legacy builder is deprecated" icon="container" defaultOpen>
    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:

    ```bash theme={"system"}
    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](https://docs.docker.com/engine/install/ubuntu/)
    and install:

    ```bash theme={"system"}
    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:

    ```bash theme={"system"}
    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.
  </Accordion>

  <Accordion title="The CLI cannot import rich" icon="terminal">
    Activate the project virtual environment and install root dependencies:

    ```bash theme={"system"}
    source .venv/bin/activate
    python3 -m pip install -r requirements.txt
    ```
  </Accordion>

  <Accordion title="Storage directories are missing" icon="folder-x">
    Run setup instead of creating ad-hoc container-only paths:

    ```bash theme={"system"}
    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.
  </Accordion>

  <Accordion title="Backend cannot open the database" icon="database-zap">
    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:

    ```bash theme={"system"}
    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.
  </Accordion>

  <Accordion title="Frontend cannot read key.pem" icon="key-round">
    Do not make the host key world-readable. Run:

    ```bash theme={"system"}
    python3 p-bitm.py up --build
    ```

    The frontend Dockerfile copies the key with ownership for its unprivileged
    nginx user.
  </Accordion>

  <Accordion title="A service is unhealthy" icon="heart-pulse">
    ```bash theme={"system"}
    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.
  </Accordion>

  <Accordion title="Browser session is blank or slow" icon="monitor-x">
    Check campaign and target-session status, then inspect logs:

    ```bash theme={"system"}
    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.
  </Accordion>

  <Accordion title="A required port is already in use" icon="unplug">
    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.
  </Accordion>

  <Accordion title="Doctor reports a database warning" icon="triangle-alert">
    Stop writes, create a complete storage backup, and run `doctor`. Do not delete
    the database as an initial repair step.
  </Accordion>
</AccordionGroup>