Skip to main content
This page covers the most common issues you might encounter when using mkdb. Most problems are related to Docker availability, port availability, or container name conflicts.
If mkdb cannot connect to Docker, you’ll see:
Start Docker Desktop, or if you’re running Docker Engine directly, ensure the daemon is active. You can verify Docker is running with:
If the command returns an error, start Docker before retrying your mkdb command.
When you run mkdb start without --port and the default port is occupied, mkdb automatically selects the next available port. You’ll see a warning like:
No action is required. mkdb handles this automatically, checking up to 100 ports from the default.
If you pass --port with a value that is already in use, mkdb returns an error instead of selecting a different port:
Either omit --port to let mkdb choose an available port automatically, or specify a different port:
If a container with the name you specified already exists, mkdb returns:
Choose a different name, or remove the existing container first:
Removing a container permanently deletes the container and its volume. Make sure you no longer need the data before running mkdb rm.
When mkdb cannot create the volume directory at the path you specified, you’ll see:
Ensure you have write permissions to the path you passed to --volume. Alternatively, use a named volume, which mkdb manages for you under ~/.local/share/mkdb/volumes/:
If you run mkdb creds rotate on a database that was created with --no-auth, the command will fail. Unauthenticated databases do not store credentials and do not support password rotation.Use mkdb creds get to confirm whether credentials exist for the container:
If no credentials are returned, the database was created without authentication. To use credential management, recreate the database with authentication enabled:
When prompted, confirm that you want to enable authentication. Omit --no-auth to ensure credentials are generated and stored.
mkdb containers have a TTL (time to live) and are automatically removed when they expire. The default TTL is 2 hours. If you restart your machine or come back to a session after some time, the container may have been cleaned up.Check your current containers with:
To prevent future expiry, extend the TTL of a running container before it expires:
When creating a new container, set a longer TTL upfront:

​
Getting more help

  • Logs: Check ~/.local/share/mkdb/mkdb.log for detailed output from recent mkdb commands.
  • Issues: File a bug report or feature request at github.com/pbzona/mkdb/issues.
  • Flag reference: Run mkdb --help or mkdb <command> --help to see all available flags for any command.