Troubleshooting¶

Common issues and solutions for the OpenCode Home Assistant integration.

Connection Issues¶

Integration not connecting¶

Symptoms: Integration shows as disconnected, no entities appear.

Solutions:

Verify OpenCode is running with the plugin installed:

# Check if plugin is in opencode.json
cat ~/.config/opencode/opencode.json | grep ha-opencode

Check if the plugin is paired:

# Config file should exist after pairing
cat ~/.config/opencode/ha-config.json

Verify access token is valid:
Go to your HA profile
Check "Long-Lived Access Tokens"
Revoke and create a new one if needed
Check Home Assistant logs:
Settings > System > Logs
Filter for "opencode"

Pairing fails¶

Symptoms: "Invalid pairing code" or connection refused.

Solutions:

The pairing code expires after 5 minutes - generate a new one

Verify your HA URL is accessible:

curl http://homeassistant.local:8123/api/

Check firewall rules allow the connection
Try using IP address instead of mDNS hostname

Disconnects frequently¶

Symptoms: Entities become unavailable intermittently.

Solutions:

Check network stability between OpenCode and HA
Verify HA is not restarting/updating
Check HA logs for WebSocket errors
The plugin auto-reconnects - wait 5-10 seconds

Entity Issues¶

Entities not updating¶

Symptoms: State shows old values, tokens don't increase.

Solutions:

Verify the WebSocket connection is active:
Check integration status in Devices & Services
Look for connection indicator
Force entity refresh:
Developer Tools > Services
Call homeassistant.update_entity on OpenCode entities
Check HA logs for errors
Restart OpenCode and check if updates resume

Entities unavailable¶

Symptoms: All entities show "Unavailable".

Solutions:

This is normal when OpenCode disconnects
Entities return when OpenCode reconnects
Start a new OpenCode session
If persistent, re-pair the integration

Wrong session data¶

Symptoms: Entities show data from different session.

Solutions:

Each session creates unique entities
Check you're looking at the right device
Old sessions may linger - refresh the page

Card Issues¶

Card not appearing¶

Symptoms: "Custom element doesn't exist" error.

Solutions:

Verify the resource is added:
Settings > Dashboards > Resources
Check /local/opencode-card.js is listed
Verify the file exists:
```
ls -la config/www/opencode-card.js
```
Clear browser cache:
Hard refresh (Ctrl+Shift+R)
Or clear site data
Check browser console for JavaScript errors

History not loading¶

Symptoms: Spinner shows indefinitely.

Solutions:

Verify the session is connected
Check HA logs for history errors
Try a different session
Refresh the page and try again

Permission buttons not working¶

Symptoms: Click approve/reject, nothing happens.

Solutions:

Check browser console for errors
Verify the permission is still pending
Check HA logs for service call errors
Try responding via Developer Tools > Services

Blueprint Issues¶

Notifications not sending¶

Symptoms: No mobile notifications appear.

Solutions:

Verify notification service is correct:
Check exact service name (e.g., notify.mobile_app_phone)
Test with Developer Tools > Services
Check mobile app is connected to HA
Check notification channel settings (Android)
Verify automation is enabled

Permission response not working¶

Symptoms: Tap approve, but permission stays pending.

Solutions:

Both blueprints must be installed
Check automation logs:
Settings > Automations > click automation > Traces
Verify permission_id is being passed correctly
Check HA logs for service call errors

Logs¶

Enable Debug Logging¶

Add to configuration.yaml:

logger:
  default: warning
  logs:
    custom_components.opencode: debug

Restart Home Assistant to apply.

View Logs¶

Settings > System > Logs
Filter for "opencode"
Click "Load Full Logs" for more detail

Plugin Logs¶

The plugin logs to terminal when notifications are triggered. Check OpenCode output for:

Connection status
Command received
Errors