Proxmox Integration Errors in Home Assistant: Fix Guide

Updated 6 November 2026 · Standard formula, shown below

This guide walks you through diagnosing and fixing common errors when integrating Proxmox with Home Assistant, so you can reliably monitor and control your virtual machines and containers from your dashboard. You’ll learn the standard causes—authentication issues, API misconfigurations, and network problems—and the exact steps to resolve them.

What You’ll Need

Access to your Proxmox web interface (root or a user with API privileges)
Home Assistant with admin access (to edit configuration.yaml and restart)
SSH or console access to the Proxmox host (for testing API connectivity)
The IP address or hostname of your Proxmox server
A text editor for editing configuration files

Step-by-Step

Check the Home Assistant logs for the exact error. Go to Settings → System → Logs and look for entries related to proxmox. Common errors include 401 Unauthorized, Connection refused, or Invalid response from API. Note the exact message—it will guide your next steps.
Verify your Proxmox credentials. The integration uses a token or username/password. If you’re using a token, ensure it’s still valid and has the correct permissions. For a user, make sure the password hasn’t changed. Test the credentials manually by opening a browser and visiting https://<your-proxmox-ip>:8006/api2/json/version with the credentials in the URL (e.g., ?username=root@pam&password=yourpassword)—if you get a JSON response, the credentials work.
Confirm the API is reachable from Home Assistant. From a terminal on the Home Assistant machine (or using the SSH add-on), run: curl -k https://<your-proxmox-ip>:8006/api2/json/version. If it fails, the network or firewall is blocking access. Ensure port 8006 is open between Home Assistant and Proxmox.
Check the Proxmox user permissions. The user or token must have at least PVEVMUser role on the relevant resources. In Proxmox, go to Datacenter → Permissions → Users and edit the user, or for tokens, check the token’s privileges under Datacenter → Permissions → API Tokens. Assign the role if missing.
Review your Home Assistant configuration. Open configuration.yaml and find the proxmox section. Ensure the host is the exact IP or hostname, port is 8006 (default), verify_ssl is set to false if you haven’t configured a valid certificate, and the username includes the realm (e.g., root@pam). Example:

proxmox:
  host: 192.168.1.100
  port: 8006
  username: root@pam
  password: yourpassword
  verify_ssl: false
  nodes:
    - node: pve
      vms:
        - 100
        - 101
      containers:
        - 102

Test the API with the same parameters. Use a tool like Postman or curl to replicate the exact API call Home Assistant makes. For example, to list VMs: curl -k -u 'root@pam:yourpassword' https://192.168.1.100:8006/api2/json/cluster/resources. If this returns data, the issue is in Home Assistant’s configuration.
Restart Home Assistant after any configuration change. Go to Settings → System → Restart. Then check the logs again for new errors.
If using a token, ensure the token ID is correct. In configuration.yaml, when using a token, you must specify token_id and token_secret instead of password. The token ID is in the format user@realm!tokenname. Double-check for typos.
Check for IPv6 vs IPv4 issues. If your Proxmox host resolves to an IPv6 address but Home Assistant is on IPv4, or vice versa, the connection may fail. Use the IP address directly in the configuration to bypass DNS issues.
Update the integration. If you’re using the built-in integration, ensure Home Assistant is up to date. If you’re using a custom integration (like the community ‘Proxmox VE’ integration), update it via HACS or manually.

Common Mistakes

Using the wrong username format: For Proxmox, the username must include the realm, like root@pam or user@pve. Omitting the realm causes authentication failures.
Forgetting to disable SSL verification: If you haven’t set up a proper certificate, you must set verify_ssl: false. Otherwise, the connection fails with a certificate error.
Incorrect port: The default API port is 8006, not 443 or 8007. Using the wrong port leads to connection refused.
Not specifying the node correctly: The node must match the exact name in Proxmox (e.g., pve). Check the node name in the Proxmox web interface.
Using the wrong VM/container IDs: The IDs in the configuration must match the actual VM/container IDs on the Proxmox host. If an ID doesn’t exist, the integration may fail to load entirely.

Tips

Use a dedicated API token instead of a password. Tokens are more secure and can be revoked independently. Create one in Proxmox under Datacenter → Permissions → API Tokens and assign the PVEVMUser role.
Test the API with curl before touching Home Assistant. This isolates whether the problem is with the API or the integration.
Enable debug logging for the integration. In configuration.yaml, add:

logger:
  logs:
    homeassistant.components.proxmox: debug

This gives you detailed logs that often reveal the exact API call failing.
Keep your Proxmox and Home Assistant versions in mind. Older Proxmox versions may have API quirks. Check the integration documentation for any version-specific notes.

Troubleshooting

If the steps above don’t resolve the issue, try these additional checks:

Check the Proxmox access log. On the Proxmox host, view /var/log/pveproxy/access.log to see if API requests are arriving. If you see requests but they return errors, the issue is with authentication or permissions.
Try a different user. Create a new user in Proxmox (e.g., ha-user@pve) with the PVEVMUser role and test with that user. This helps rule out a corrupted user account.
Check for network firewalls. Ensure no firewall on the Proxmox host or between the machines is blocking port 8006. Use telnet <ip> 8006 from Home Assistant to test connectivity.
Verify the API token has the correct privileges. For tokens, the privilege must be set on the token itself, not just the user. In the Proxmox web UI, after creating a token, click on it and ensure the ‘Privilege Separation’ is unchecked or the token has the correct role assigned.
Check Home Assistant’s network configuration. If Home Assistant is in a Docker container or VM, ensure the network mode allows outbound connections to your Proxmox host.
Look for rate limiting. Proxmox may temporarily block after multiple failed login attempts. Wait a few minutes and try again.

Frequently Asked Questions

Why do I get ‘401 Unauthorized’ even with the correct password?

This often happens when the username doesn’t include the realm (e.g., root instead of root@pam). Also, ensure the user has the required permissions on the node and VMs.

Can I use a token instead of a password?

Yes, and it’s recommended. Use token_id and token_secret in the configuration. The token ID must be in the format user@realm!tokenname.

Why does the integration work for VMs but not containers?

This is usually a permissions issue. The user or token needs the PVEVMUser role on the container resources. Check the permissions in Proxmox and ensure the container IDs are correctly listed.

How do I find the correct node name?

Log into the Proxmox web interface and look at the left sidebar. The node name is the top-level item under ‘Datacenter’ (e.g., ‘pve’).

What does ‘Invalid response from API’ mean?

This typically indicates that the API returned data in an unexpected format, possibly due to a Proxmox version mismatch or a bug in the integration. Update both Proxmox and Home Assistant to the latest versions.

Do I need to open a port on my router for this to work?

Only if Home Assistant is on a different network than Proxmox. For local setups, no port forwarding is needed. If you’re accessing remotely, you’d need a VPN or reverse proxy, but that’s beyond this integration’s scope.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.