Troubleshooting managed configuration
When implementing managed configuration in an enterprise environment, you may encounter some common issues often caused by file location, permissions, or syntax errors.
Locked configuration not working
If your locked configuration is not being applied, try the following solutions:
- Verify file locations are correct for your operating system.
- Check file permissions (files must be owned by root/administrator).
- Ensure JSON syntax is valid (use a JSON validator).
- Restart Podman Desktop after creating configuration files.
Settings not being enforced
If settings appear to be locked but values are not being enforced correctly:
- Check that the key name in
locked.jsonexactly matches the key indefault-settings.json. - Verify the configuration key uses dot notation (e.g.,
proxy.http, notproxy: { http: ... }). - Check console output for error messages.
Verifying configuration is loaded
To verify that your managed configuration is being loaded correctly:
- Open Podman Desktop.
- Go to Help > Troubleshooting, and select the Logs tab to check for messages such as:
- Look for messages in the console like:
[Managed-by]: Loaded managed ...[Managed-by]: Applied default settings for: setting.key1, setting.key2
- If you don't see these messages, the configuration files may not be in the correct location or may have syntax errors.
The "Applied default settings" message only appears when settings are copied from default-settings.json to the user's settings.json. This occurs once per setting when it doesn't already exist in the user's configuration.
Verifying if a value is locked by the managed-by configuration
To verify in the GUI if a value is locked by your managed-by configuration:
- Open Podman Desktop.
- Go to Settings > Preferences.
- Find your managed-by value:

- Confirm that it has the Managed label applied.
File permission issues
On Linux and macOS, managed configuration files must have appropriate permissions:
- Files must be owned by root/administrator
- Files should be readable by all users but writable only by root/administrator
- Use
chmod 644for the configuration files on Linux/macOS
macOS MDM preferences
A profile is installed, but the settings do not appear
-
Make sure that the preference domain is
io.podman_desktop.PodmanDesktop. -
Make sure that the file exists at the device or per-user path.
-
For a per-user file, make sure that the directory name matches the account's short name.
-
Run this command as the affected user:
/usr/bin/plutil -convert json -o - "/Library/Managed Preferences/io.podman_desktop.PodmanDesktop.plist"For a per-user policy, use that user's plist path instead.
-
Make sure that the command succeeds without
sudo. -
Make sure that the output contains top-level dotted keys, such as
telemetry.enabled. -
Make sure that the file contains the application settings dictionary without a configuration profile wrapper.
-
Restart Podman Desktop.
-
Open Help > Troubleshooting > Logs.
-
Find the messages that start with
[Managed-by]:.
Log messages
| Message | Meaning |
|---|---|
Loaded managed preferences from: | The reader accepted the plist at the displayed path. This does not establish that every setting is valid or locked. |
Failed to read managed preferences from | The reader ignored the file. The accompanying error identifies the read, conversion, or format failure. |
Managed preferences must contain a dictionary | The plist does not contain a settings dictionary at its root. |
Managed preference locks must contain an array of strings | The locked value is invalid. The reader ignores the entire file, including its other settings. |
The Applied default settings for: message lists defaults that fill missing user values.
It does not report per-user overrides or every enforced value.
Podman Desktop can load a valid policy without this message.
A missing plist does not produce a log message.
A value loads, but does not stay locked
- Put the key in the device plist's
lockedarray or inlocked.json. - Supply its managed value in the device plist or
default-settings.json. - Make sure that the key names match exactly, including capitalization and dots.
- Make sure that the value type matches the settings reference.
- Restart Podman Desktop.
A per-user plist cannot add locks. Unlocked device defaults do not replace existing user values. A lock without a managed value does not enforce a value, even if the UI displays a lock.
A changed or removed policy leaves the old value
- Restart Podman Desktop after the policy change.
- Compare the active sources with the configuration precedence rules.
- To remove a lock, remove the key from the device plist's
lockedarray andlocked.json, where applicable. - After policy removal, update any unwanted value that remains in the user's preferences.
Policy removal does not erase saved user values. An empty device lock list does not clear JSON locks.