Skip to content

Troubleshooting

Arie J. Godschalk edited this page Nov 15, 2026 · 4 revisions

Troubleshooting

A field does not appear in a Flow card

  • Confirm that the field is configured and saved in the AVD's repair/settings screen.
  • Confirm that the selected device is the intended AVD.
  • Reopen the Flow-card selector and search for the configured field name.
  • Check that the selected card expects the field's type (text, number, Yes/No, button, list, or camera).

A Flow triggers, but the AVD value is stale

An AVD only changes when a Flow, reflection, API call, or other app behavior writes its field. Add or repair a Flow that mirrors the real device's state to the AVD. If both directions are automated, test for feedback loops.

To show a text label on the tile, verify that the intended Text field is selected in the Homey mobile device settings and update it with Set Text.

A real field or default Flow card is missing

Check the selected field type and Show as representation: the real-field checkbox is not available for every field. For a standard capability, save the setting and verify the resulting Homey cards; duplicate capabilities, device class, other capabilities, and Homey version can affect what appears. Custom lists use the app's AVD List cards instead. See the checkbox matrix and migration guidance.

A real device receives duplicate commands

Check whether both React and a Flow are commanding the same property, or both Homey default and AVD-specific triggers are active. Nothing else suppresses the explicit AVD When-card execution, not necessarily a default Homey trigger or a separate React write. Test the paths separately; see Reflection and React.

A capability listener does not fire

  • Verify the selected device and capability in autocomplete.
  • Confirm that the capability actually changes on the device.
  • Check that the underlying device app/driver is online and reporting state changes to Homey.
  • Try a simple test Flow that uses the capability listener and sends a notification with its value token.
  • Remember that user/client tokens require origin information from Homey and may be empty for some changes.

The listener does not make an unsupported or unreported capability observable.

A zone action does not affect an expected device

  • Confirm the device is in the selected zone (or in an included subzone).
  • Confirm the device class, brand, and device type filters match it.
  • Confirm that the device exposes the selected capability.
  • Check the value type and allowed values accepted by its driver.
  • For JSON values, ensure the input is valid JSON and that text values use double quotes.

Insight value is missing or unexpected

The historical retrieval action depends on Homey Insight data for the capability. Check whether the capability has an Insight log, whether the requested time is in the available history, and whether the chosen capability is the one that records the value. Setting minutes to zero requests the latest value; it does not create historical records.

User and client tokens are only populated when Homey stored that information.

The error-wait condition does not continue

  • Verify that the device accepts the requested Boolean capability.
  • Trigger the normal device action once and inspect the error details returned by the device app/driver.
  • Enter the error name expected by the condition, not an approximate message phrase.
  • Confirm that repeated writes are safe for this device.
  • Check that the condition's wait window has not expired.

This card retries the write while waiting; do not use it as an ordinary pause/delay.

A template imports but does not work

Imported Flows may reference devices, variables, apps, and users that exist only on the creator's Homey. Use the import workflow to replace references, install required apps, and then inspect the resulting Flow. For HCS templates, check whether the required community app is installed. See Templates and The Exchanger File.

A changed icon is not visible

The community instructions note that a changed icon already in use may require restarting Device Capabilities before it updates. Reopen the device after the restart and verify the icon selection.

BLL expression is unavailable

Install Better Logic Library only if you need a feature explicitly marked as a BLL expression. Basic AVD setup and the app's other Flow cards do not require BLL.

Report a problem

For support, include the app version, Homey model/software version, exact card and arguments, expected result, actual result, and relevant error details. Remove private data from screenshots and logs. Use the GitHub issue tracker for reproducible defects, or the community topic for questions and troubleshooting.

Clone this wiki locally