Troubleshooting

“Command not found” after activation

1. Verify a crate is active: check if $BULKERCRATE is set.
2. Verify the command exists in the crate: bulker crate inspect <crate>.
3. Check your PATH includes the crate directory: echo $PATH.
4. Make sure the shell function is loaded. Run type bulker — it should show a shell function, not just a binary path. If not, re-run eval "$(bulker init-shell bash)" or restart your shell.

Container not starting

1. Check which engine is configured: bulker config get container_engine.
2. Verify the engine is running: docker info or apptainer version.
3. Check the image exists: docker pull <image> manually.
4. Print the exact command being run: bulker exec -p <crate> -- <command> or set BULKER_PRINT_COMMAND=1.

Permission denied

• Files owned by root: The container may be running as root. Check if the manifest sets no_user: true — if so, files created inside the container will be owned by root.
• Cannot access mounted volumes: Ensure the volume paths exist on the host and are readable.
• macOS vs Linux: On macOS, system_volumes is false by default (system paths like /etc/passwd don’t exist as on Linux). If you see permission errors related to user mapping on macOS, check that host_network and system_volumes are both false.

Manifest not found

1. Check the registry URL: bulker config get registry_url.
2. Verify the format: namespace/crate:tag (e.g., databio/pepatac:1.0.14).
3. Try loading from a local file: bulker activate ./path/to/manifest.yaml.
4. Check if the manifest exists at the registry: visit http://hub.bulker.io/namespace/crate_tag.yaml in a browser.

Slow first activation

The first time you activate a crate, bulker:

1. Fetches the manifest from the registry (fast).
2. Creates shimlinks (fast).
3. On the first command invocation, Docker pulls the image (can be slow).

To avoid the delay at command time, pre-cache with image pulls:

bulker crate install <crate> -b

The -b flag pulls all container images upfront.

Shell function not working

If bulker activate prints output but doesn’t change your PATH:

1. The shell function may not be loaded. Check: type bulker.
2. Re-add to your shell RC file: eval "$(bulker init-shell bash)" (or zsh).
3. Restart your shell or source ~/.bashrc.

For scripts and CI where the shell function isn’t available, use bulker exec instead.

Config file issues

Bulker works without a config file — it auto-detects your container engine and creates one on first use at ~/.config/bulker/bulker_config.yaml. If you need to reset your config:

bulker config init --force

To see the effective config (including defaults for fields not in the file):

bulker config show --effective

Activation fails on read-only /tmp

Bulker creates a temporary directory of shimlinks on each activation. By default this uses the system temp directory (usually /tmp). If /tmp is read-only or unavailable (e.g., in restricted HPC environments), set TMPDIR to a writable location:

export TMPDIR=/scratch/$USER/tmp
mkdir -p "$TMPDIR"
bulker activate demo

Bulker uses the standard TMPDIR convention, so this works with any writable directory. For a complete guide to running bulker on HPC clusters, see Running Bulker on HPC Clusters.

Apptainer-specific issues

• First run is slow: Apptainer converts Docker images to .sif files on first use. Subsequent runs use the cached .sif.
• Image cache location: Check bulker config get apptainer_image_folder (default: ~/.local/share/apptainer/images).
• Both apptainer and singularity work: bulker uses whichever is on your PATH.