Troubleshooting and Debugging

Learn how to troubleshoot and debug Podman containers using built-in tools like `inspect`, `logs`, `exec`, and systemd journal logs.

Even with a solid setup, container issues are bound to happen. In this lesson, you’ll learn how to debug Podman containers, interpret logs, inspect configurations, and resolve common problems.

🛠 Inspecting Containers

Start with podman inspect to view everything about a container:

podman inspect <container-id>

This gives you:

• Environment variables
• Volume mounts
• Network settings
• Restart policies
• Container state and exit codes

📦 Use jq or grep to filter specific values:

podman inspect <id> | jq '.[0].State.ExitCode'

📜 Viewing Logs

To see standard output and error logs:

podman logs <container-id>

To stream logs live:

podman logs -f <container-id>

If using systemd:

journalctl --user -u container-<name>

🧠 Podman containers integrate cleanly with the Linux journal when managed via systemd.

🧪 Executing Commands in a Running Container

Use exec to get a shell or run diagnostics inside a container:

podman exec -it <container-id> sh

Or if it has bash:

podman exec -it <container-id> bash

This is great for checking filesystem paths, environment variables, or running troubleshooting tools (e.g. curl, ping).

❌ Common Errors and Fixes

“Image not found”

Check spelling and tags:

podman pull <correct-image-name>

Port binding fails

Ensure the port is free or mapped correctly:

podman run -p 8080:80 ...

Permission denied (rootless volume)

Make sure the host folder is writable by your user:

mkdir -p ~/mydata
chmod 755 ~/mydata

Mount it:

podman run -v ~/mydata:/data ...

Container immediately exits

Check the container’s command:

podman inspect <id> | jq '.[0].Config.Cmd'

Or run with an interactive shell:

podman run -it <image> sh

🧹 Cleaning Up

Remove exited containers:

podman container prune

Remove dangling images:

podman image prune

Remove unused volumes:

podman volume prune

🧰 Useful Tools

Next up: Migration Project

< Previous Next >

You can use the arrows  ← → on your keyboard to navigate between lessons.