Troubleshooting

Troubleshooting should connect symptoms to source-backed checks without inventing unsupported error text or automatic repair behavior. Start with the smallest check that proves where the problem is: shell path, Engine, runtime, image, container, network, or storage.

Start With Status And Logs

mactain engine status
mactain system logs --lines 200

Use logs to understand what happened, but avoid sharing secrets, credentials, tokens, or private registry passwords when asking for help.

Command Reference

Command	Description	Typical use
`command -v mactain`	Checks whether the shell can find the CLI shim.	Diagnose `command not found`.
`ls -l /usr/local/bin/mactain`	Checks whether the expected shim exists.	Distinguish shell PATH issues from install issues.
`mactain engine status`	Checks Engine reachability.	Determine whether failures are before container runtime.
`mactain runtime install`	Installs runtime assets.	Fix missing runtime asset reports.
`mactain system logs --lines 200`	Shows a bounded recent log sample.	Collect source-backed diagnostic context.
`mactain image pull <reference>`	Pulls an image directly.	Separate registry/image failures from container flags.
`mactain container status <name>`	Shows runtime status for one container.	Check running state, health, IP, and ports.
`mactain container logs <name>`	Shows container logs.	Diagnose app startup and runtime failures.
`mactain network membership list`	Shows network scope memberships.	Diagnose service discovery and scope issues.
`mactain volume inspect <name>`	Shows volume metadata.	Diagnose missing persistent data.
`mactain blueprint validate <path>`	Validates Blueprint syntax and fields.	Diagnose Blueprint failures before runtime changes.
`mactain blueprint plan <path>`	Previews Blueprint runtime work.	Understand what MacTain will create or start.

Defaults And Behavior

Start with the smallest check that isolates the failing layer: CLI, Engine, runtime assets, image, container, network, volume, or Blueprint.
Do not keep retrying container commands until the Engine and runtime checks pass.
Logs can contain sensitive values. Redact credentials, tokens, private registry passwords, and private customer data before sharing.
Troubleshooting docs should not promise automatic repair unless the CLI source documents that behavior.

Practical Use Cases

Use case: `mactain` command is not found

Use this when Terminal says command not found: mactain.

command -v mactain
ls -l /usr/local/bin/mactain
/usr/local/bin/mactain --help

If command -v mactain prints nothing but /usr/local/bin/mactain exists, open a new Terminal session and check whether /usr/local/bin is in PATH. If the file does not exist, reinstall MacTain from the approved installer for your channel.

Use case: Engine is not available

Use this when container commands fail before they reach a running workload.

mactain engine status
mactain engine start --help
mactain system logs --lines 200

Do not keep retrying container commands until the Engine status is understood.

Use case: runtime assets are missing

Use this when a container command reports that runtime assets are unavailable.

mactain runtime install
mactain runtime docs

Runtime assets are local artifacts required to run containers. If install or update fails, collect recent system logs before changing the container command.

Use case: image pull fails

Use this when MacTain cannot fetch an image.

mactain image pull docker.io/library/nginx:latest --refresh
mactain registry credentials list
mactain registry credentials test --help

Public images should not require credentials. Private registries may require Keychain-backed credentials.

Use case: container starts but the app is unreachable

Use this when the container is running but the browser or client cannot reach the service.

mactain container status web
mactain container logs web --lines 100
mactain network membership list --container web

Confirm that the service listens on the container port and that the container was started with the expected --publish mapping.

Use case: Secure Egress container is blocked

Check the saved VPN connection and assigned container separately:

mactain vpn status media-vpn --json
mactain vpn test media-vpn --timeout 30 --json
mactain container inspect qbittorrent --json

Confirm that the connection includes 0.0.0.0/0 and IPv4 DNS. A missing provider endpoint, conflicting DNS policy, or unverified protected path keeps the assigned container blocked rather than starting it through ordinary Internet access. See Secure Egress troubleshooting for NAT-PMP and policy-change cases.

Use case: data is missing after replacing a container

Use this when an app starts clean instead of seeing previous data.

mactain volume list
mactain volume inspect media-cache
mactain volume fs list media-cache /

Containers are not a substitute for persistent volumes. Put data that must survive container replacement in a volume.

Common Symptoms

Symptom	First checks
CLI command is not found	Run `command -v mactain`, then check `/usr/local/bin/mactain`.
Engine is not available	Run `mactain engine status`, then check recent system logs.
Runtime assets are missing	Run `mactain runtime install` and review `mactain runtime docs`.
Image cannot be pulled	Test the image pull directly and review registry credentials.
Container starts but app is not reachable	Check container status, logs, port publishing, and network memberships.
Secure Egress container is blocked	Check VPN status, full-tunnel IPv4, DNS, and the container protection state.
Data is missing after replacement	Inspect volumes and confirm the workflow uses persistent storage.
Blueprint start fails	Validate and plan before starting, then inspect component container logs.

Useful Commands

mactain container logs <id-or-name>
mactain container inspect <id-or-name>
mactain blueprint validate ./myapp.toml
mactain blueprint plan ./myapp.toml
mactain system storage reclaimable

Next Steps

Return to the task page that matches the symptom after collecting the first diagnostic output.