Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Troubleshoot issues

Red Hat build of Podman Desktop 0.9

Explore how to troubleshoot connection, logs, proxy, and registry related issues.

Red Hat Customer Content Services

Abstract

Troubleshoot issues in Red Hat build of Podman Desktop using the following information.

Preface
Copy link

Troubleshooting guidance for critical Red Hat build of Podman Desktop operations includes:

  • Connection or execution errors: Use integrated troubleshooting tools for log inspection, connection verification, and data store management to ensure optimal performance.
  • Proxy configuration: Resolve installation barriers in restricted networks and VPN access issues, and learn how to route Podman machine traffic through a corporate proxy.
  • Registries configuration: Fix authentication failures and access registries that use insecure or self-signed certificates.
  • Container logs accessibility: Find missing log outputs by verifying the running state of both the container and the Podman machine.

If you encounter connection issues or execution errors, use the built-in troubleshooting tools to view logs, verify connections, and manage data stores.

1.1. Connection failures or task execution errors
Copy link

Issue
General connection failures or task execution errors occur within the application.
Solution
  1. Access logs: Click the Troubleshooting icon in the status bar, and select the Logs tab to view real-time internal events.
  2. Export diagnostics: If the issue persists, go to the Gather Logs tab and click Collect and save logs as .zip to generate a log package for support analysis.
Issue
The container engine is unresponsive or the UI is disconnected from the engine socket.
Solution
  1. Verify connectivity: Navigate to the Repair & Connections tab on the Troubleshooting page, and click Ping to check engine responsiveness.
  2. Reset connections: Click Reconnect Providers on the same page to refresh the connection to the container engine socket.
  3. Check container status: Use the Check containers button to verify the response time and availability of all existing containers.
Issue
UI synchronization issues, such as missing containers or images that should be visible.
Solution
  1. Inspect Stores: Open the Stores tab in the Troubleshooting section, and click the link for the relevant component, such as containers or images.
  2. Force refresh: Compare the store count with the UI; if they differ, click Refresh to manually synchronize the data from the back-end.
  3. Clear history: If the event log is cluttered, click Clear to remove historical data and allow the store to capture fresh events.

Chapter 2. Troubleshoot container issues
Copy link

Troubleshoot issues encountered when viewing container logs in Red Hat build of Podman Desktop. The primary focus is on resolving instances where the log stream is empty or inactive.

2.1. Fix empty or missing container logs
Copy link

Issue
The Logs tab for a container is empty or does not show any new logs.
Solution
  1. Verify container state: Ensure that the container you are examining is currently in a Running state.
  2. Verify application output: Confirm the application inside the container sends its logs to the console (stdout/stderr) for Podman to display.
  3. Check Podman machine: Ensure the underlying Podman machine is running and connected. Go to Settings > Resources, and verify the status of the machine.
Issue
The Podman machine is not running, which prevents access to container logs.
Solution

Viewing container logs requires an active Podman Machine.

  1. Go to Settings > Resources in the navigation pane.
  2. Locate your Podman machine, such as podman-machine-default.
  3. If the status is Stopped, click the Start icon to launch the machine.

Chapter 3. Troubleshoot container registry issues
Copy link

Resolve container registry authentication and connection issues in Red Hat build of Podman Desktop. These solutions cover standard login errors and manual configurations for connecting to registries using insecure or self-signed certificates.

Issue
Logging in to a pre-configured or custom registry fails, and an error message is displayed.
Solution

This typically indicates incorrect registry credentials. Perform the following actions:

  • Re-enter your Username and Password (or OAuth secret) carefully.
  • For custom registries, ensure the Registry Location (URL) is correct, such as https://myregistry.tld.
  • Click Login again after entering the corrected credentials.
Issue
The container registry uses an insecure certificate. Because of this, Red Hat build of Podman Desktop shows a warning pop-up when you set up the registry.
Solution
  1. In the warning pop-up, click Yes to add the registry despite the certificate issue.

  2. Manually authorize access to the insecure registry by editing the registries.conf configuration file.

    Expand
    Table 3.1. Edit registries.conf (requires root/superuser privileges)
    Operating systemHow to access terminalConfiguration file location

    Windows/macOS (Podman machine)

    Go to Settings > Resources. In the Podman tile, select More Options > Open Terminal.

    Run podman machine ssh --username root <optional_machine_name>

    /etc/containers/registries.conf (inside the machine)

    Linux (Host)

    Run sudo su -

    /etc/containers/registries.conf (on the host)

  3. Open the /etc/containers/registries.conf file in a text editor. 

    # vi /etc/containers/registries.conf
    Copy to Clipboard Toggle word wrap

  4. Add a section for each insecure registry, setting insecure = true. 

    [[registry]]
location = "my-registry.tld"
insecure = true
    Copy to Clipboard Toggle word wrap

  5. Restart Podman to apply the changes:

    • Windows/macOS: Go to Settings > Resources and restart the Podman machine.
    • Linux (rootless): Run pkill podman.
    • Linux (rootful): Run sudo systemctl restart podman.

Deploy Red Hat build of Podman Desktop in restricted or proxy-dependent networks by resolving installation failures in air-gapped environments. Fix VPN-related connectivity issues by enabling the User Mode Networking option. You also find steps to route container traffic through corporate proxies.

Issue
When using a Virtual Private Network (VPN), the host computer cannot access resources exposed by the Podman machine because the machine receives a distinct network address.
Solution
When setting up the Podman machine, enable the User mode networking (traffic relayed by a user process) option. This routes the network traffic through your host, allowing access to the machine’s exposed resources.
Issue
Your host machine has internet access, but containers started in Red Hat build of Podman Desktop cannot reach the network. This happens because containers do not automatically receive the proxy settings from the applicaton UI or operating system.
Solution
To manually configure a proxy for your containers, refer to Configure proxy settings on macOS and Windows and Configure proxy settings on Linux.
Issue
When using a proxy that requires custom Certificate Authorities (CAs), the Podman machine fails to verify secure connections.
Solution
To use a custom CA with your proxy, refer to Configure proxy settings on macOS and Windows and Configure proxy settings on Linux.

Legal Notice
Copy link

Copyright © Red Hat.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top