Troubleshooting

Common issues and solutions for Home Assistant Plasmoid

This guide helps you resolve common issues with the Home Assistant Plasmoid.

Installation Issues

Qt WebSocket package is not installed

The plasmoid requires the Qt WebSocket package to communicate with Home Assistant. If you see errors about missing WebSocket components, install the appropriate package for your distribution:

Distribution	Required Package
Debian, Ubuntu	qml6-module-qtwebsockets
Arch	qt6-websockets
Fedora	qt6-qtwebsockets-devel
openSUSE	qt6-websockets-imports
NixOS	kdePackages.qtwebsockets

After installation, restart Plasma or re-login for the changes to take effect:

# Restart Plasma session
plasmashell --replace &

The plasmoid will not function without the Qt WebSocket package. This is the most common installation issue.

KDE Wallet is not active

The plasmoid uses KDE Wallet to securely store your Home Assistant access token. If KDE Wallet is disabled or not configured, the plasmoid cannot save your credentials.

Solution:

1. Open System Settings
2. Navigate to Security & Privacy → KDE Wallet
3. Enable KDE Wallet
4. Configure a wallet (either with or without encryption)
5. Restart the plasmoid

KDE Wallet must be active before configuring the plasmoid for the first time.

Plasmoid shows configuration required

If the plasmoid displays a configuration required message, it means one or more required settings are missing:

Checklist:

• Home Assistant URL is configured
• Long-Lived Access Token is set
• At least one entity is added to the plasmoid

To configure:

1. Right-click the plasmoid
2. Select Configure Home Assistant
3. Enter your URL and token
4. Add entities in the Items tab

Connection Issues

Invalid URL format

The Home Assistant URL must include the protocol and port. Common mistakes include:

Incorrect formats:

• homeassistant.local (missing protocol)
• http://homeassistant.local (missing port for custom setups)
• http://homeassistant.local:8123/ (trailing slash)

Correct formats:

• http://homeassistant.local:8123
• https://example.duckdns.org
• http://192.168.1.100:8123

The plasmoid automatically removes trailing slashes and whitespace, but you must include the protocol (http:// or https://).

The URL is automatically converted from HTTP(S) to the WebSocket protocol (WS/WSS) internally. See Client.qml:17 for implementation details.

Authentication failed

If you see an auth_invalid error, the access token is incorrect or expired.

Solutions:

1. Generate a new Long-Lived Access Token:
   • Go to your Home Assistant profile: https://your-ha-url/profile/security
   • Scroll to Long-Lived Access Tokens
   • Click Create Token
   • Copy the token immediately (it won’t be shown again)
2. Update the token in plasmoid configuration
3. Ensure the token hasn’t been revoked in Home Assistant

Access tokens are stored securely in KDE Wallet. If you change your Home Assistant URL, you need to re-enter the token.

WebSocket connection drops

The plasmoid uses a ping-pong mechanism to keep the WebSocket connection alive. If connections drop frequently:

Common causes:

• Network instability or firewall issues
• Home Assistant server restarting
• Reverse proxy timeout settings too aggressive

How it works:

• The plasmoid sends a ping every 30 seconds (Client.qml:28)
• If no pong response is received within 30 seconds, it automatically reconnects
• Check the error string in the plasmoid interface for specific connection errors

Solutions:

• Verify network connectivity between your machine and Home Assistant
• Check Home Assistant logs for WebSocket errors
• If using a reverse proxy (nginx, Apache), increase WebSocket timeout settings
• Ensure your Home Assistant version is 2022.4 or newer

Cannot connect over HTTPS

If your Home Assistant uses HTTPS with a self-signed certificate, you may encounter connection issues.

Solutions:

• Add the certificate to your system’s trusted certificates
• Use a valid certificate from Let’s Encrypt or another CA
• For testing only: temporarily use HTTP instead of HTTPS

Never disable SSL verification in production environments. Always use valid certificates.

Entity Configuration Issues

Entities not updating

If entity states don’t update in the plasmoid:

Troubleshooting steps:

1. Verify the entity exists and is available in Home Assistant
2. Check that the entity ID is correct (case-sensitive)
3. Ensure the WebSocket connection is active (check for error messages)
4. Try removing and re-adding the entity

Technical details:

• The plasmoid subscribes to entity state changes via subscribe_entities WebSocket command (Client.qml:98)
• State updates are received as events with type event (Client.qml:64)
• Only configured entities receive update subscriptions

Service calls not working

If clicking entities or using scroll actions doesn’t trigger services:

Check:

1. The service domain and service name are correct
2. The entity supports the service being called
3. Required service data fields are properly configured
4. Check Home Assistant logs for service call errors

The plasmoid calls services using the call_service WebSocket command (Client.qml:109-117). Service call responses are handled asynchronously.

Entity shows as unavailable

If an entity displays as unavailable:

• The entity may be offline or disconnected in Home Assistant
• The entity ID may have changed
• The integration providing the entity may be disabled

Solution: Check the entity status directly in Home Assistant to confirm availability.

Debugging

Checking Logs

To view plasmoid logs and errors:

# View real-time Plasma logs
journalctl --user -f | grep plasmashell

# View QML errors
journalctl --user -f | grep qml

# Check for WebSocket errors
journalctl --user -f | grep WebSocket

Error Messages

The plasmoid exposes error messages through the errorString property (Client.qml:13). Common error messages:

Error Message	Meaning	Solution
auth_invalid	Token authentication failed	Regenerate and update access token
Component.Error	Qt component failed to load	Check Qt WebSocket package installation
Connection error	Network/WebSocket connection failed	Verify URL format and network connectivity
Empty response	No data received from Home Assistant	Check entity IDs and Home Assistant availability

Debug Mode

To enable verbose QML logging:

# Set QML debugging environment variable
export QT_LOGGING_RULES="*.debug=true;qt.*.debug=false"

# Restart Plasma
plasmashell --replace &

Verifying WebSocket Connection

You can test the WebSocket connection independently:

# Using wscat (install with: npm install -g wscat)
wscat -c ws://homeassistant.local:8123/api/websocket

# You should see:
{"type":"auth_required","ha_version":"..."}

Component Load Errors

If the plasmoid fails to load entirely, check for component errors:

# Check plasmoid package integrity
plasmapkg2 --list | grep homeassistant

# Reinstall if corrupted
plasmapkg2 -r plasma-homeassistant
plasmapkg2 -i plasma-homeassistant-*.plasmoid

Getting Help

If you continue experiencing issues:

1. Search existing issues: Check the GitHub Issues page
2. Gather information:
   • Your distribution and version
   • KDE Plasma version
   • Home Assistant version
   • Error messages from logs
   • Steps to reproduce the issue
3. File a bug report: Use the bug report template

When reporting issues, include your system information, KDE Plasma version, and relevant log output. Never include your access token in bug reports.

System Requirements

Verify your system meets the minimum requirements:

• KDE Plasma: 6.0 or newer
• Home Assistant: 2022.4 or newer
• Qt WebSocket package: Must be installed
• KDE Wallet: Must be active

Check your versions:

# Check Plasma version
plasmashell --version

# Check Qt version
qmake --version