Troubleshoot issues

Red Hat build of Podman Desktop 1.0

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

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.

Chapter 1. Troubleshoot task and connection issues through UI and CLI

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

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.

1.2. Find and send logs to receive support for prersistent issues

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.

1.3. Unresponsive container engine or disconnected UI socket

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.

1.4. Fix UI synchronization issues and missing resources

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.

1.5. Setup configuration warning persists on the dashboard

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

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

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

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.

2.2. Container logs inaccessible when Podman machine is stopped

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

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.

3.1. Login Failed errors when connecting to container registries

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.

3.2. Invalid Certificate errors when adding a container registry

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.

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

Chapter 4. Troubleshoot restricted environments and proxy configuration issues

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.

4.1. Host cannot access Podman machine resources on VPN-enabled networks

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.

4.2. Containers cannot connect to the network in proxy-restricted environments

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.

4.3. Connection errors when using proxies with custom certificates

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

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.