Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Troubleshoot issues

Red Hat build of Podman Desktop 1.1

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 helps you resolve connection or execution errors by using integrated troubleshooting tools for log inspection, connection verification, and data store management. It helps you fix proxy configuration issues in restricted networks and VPN scenarios and route Podman machine traffic through a corporate proxy. It helps you fix registry authentication failures and access registries that use insecure or self-signed certificates. It also helps you find missing container log output by verifying that both the container and the Podman machine are running.

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

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
You may need to provide detailed diagnostic information or internal event logs to technical support to resolve persistent connection failures or execution errors.
Solution

  • Share log details

    1. Click the Troubleshooting icon in the status bar, and select the Logs tab to view real-time internal events.
    2. Click the Copy To Clipboard icon to copy the log entries and paste them at the desired location.
    3. Share specific error details on the Red Hat Customer Portal to get support.

  • Export diagnostic archive

    1. Go to Troubleshooting > Gather Logs.
    2. Click Collect and save logs as .zip to generate a comprehensive diagnostic archive.
    3. Share the archive file on the Red Hat Customer Portal to get support.

  • Capture granular console logs

    To view real-time internal events and errors not captured in standard logs, open the Developer Tools window:

    • macOS: Press Cmd + Option + I

    • Windows/Linux: Press Ctrl + Shift + I or F12

      In the Developer Tools window, do the following:

      1. Select the Console tab.
      2. Right-click any log entry and select Save as…​ to export the file.
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.
Issue
The dashboard continues to display a Podman needs to be set up warning even after completing the setup wizard. Although you may see a podman is installed confirmation, the application returns to the initial setup prompt.
Solution

This issue occurs because the UI has not registered the binary location despite the extension being installed. You can resolve this discrepancy by performing one of the following steps:

  • Click the Troubleshooting icon in the status bar, select the Stores tab, and click Refresh for the relevant component. This forces the UI to re-synchronize with the Podman engine state.
  • Click the close icon on the warning shown in the dashboard.
  • Restart the Red Hat build of Podman Desktop application.

1.6. macOS: Podman command not found in terminal
Copy link

Issue
Podman is unavailable via the command line after installation. Attempting to execute the podman command results in the error: podman: command not found.
Solution

This indicates the PATH environment variable is not yet synchronized with your active terminal.

Perform one of the following steps to resolve the issue:

  • Restart the terminal: Close and reopen your terminal to ensure the shell loads the updated PATH containing the Podman binary. The binary path is /opt/podman/bin/podman.
  • Manual path update: If the issue persists, check that your shell configuration file (.bash_profile or .zshrc) includes the Podman bin directory path. Once verified, run source <file_name> to apply the changes to your current session.

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)

    Open the terminal on your machine and 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

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

    [[registry]]
location = "my-registry.tld"
insecure = true

  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.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . 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, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

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.

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 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.

Legal Notice

Theme

© 2026 Red HatBack to top