Troubleshooting
| Symptom | Check and action |
|---|---|
| Workspace requests an integration update | Update the integration including its bundled www/dashboard.html, restart HA and refresh the page. |
| Plan cannot arm | Check controller capability/heartbeat, plan validation, sensor freshness and explicit limits. Save the draft before arming. |
| Plan is armed but not active | It becomes eligible at the next local lights-on boundary. Arming never enables the engine. |
| Active plan is held or in error | Read the plan/controller error. Restore valid fresh data; use disarm for an explicit return to manual targets at a boundary. Do not bypass the required-plan latch. |
| Mapping save is rejected | The message names each entity and why: it is ON (turn it off and submit again), it reads 'unavailable' (the device must be reachable and OFF), or entity not found (check the id, or its device integration has not loaded). The wizard keeps everything you typed and shows the same step again. Also check entity domains/units, duplicate valves and revision conflicts. |
| Probe rejected for its unit | Pore EC is accepted in mS/cm, dS/m and µS/cm; moisture in % or m³/m³. Other units are converted exactly or refused. ppm is refused because the 500 or 700 scale is not something a sensor reports: expose the probe's EC reading instead. |
| Room saved but never waters, and it has one switch | Update to integration 2.18.0 / controller 0.15.1. A zone needs only its valve; pump and main-line valve are optional. Map the single switch as the zone's valve and leave pump and main-line empty. One switch cannot be used in two roles. |
| Room has a pump, shots are counted, VWC never rises | The room has never said how it is plumbed, so the controller works it out from what is mapped: an empty pump field means it never runs a pump, opens the zone switch and counts the shot as delivered. Open Rooms & setup (or Configure), choose the layout with a pump, choose the pump, save. From then on a missing pump holds the room instead of running it dry; see the first-run review. |
| Zones that do not exist report no hardware mapped (a one-zone room shows Zones 2 and 3) | The controller app was started before the integration was set up, and versions before 0.16.2 then fell back to three zones. Update to controller 0.16.2 / integration 2.19.2: it waits for a room, invents none, and picks yours up within a minute. On an older controller, turn Engine Enabled and the pump/valve switches OFF and restart the app once. |
Repairs: kill switch helper missing, asking for input_boolean.f2_control_enabled, on a room made by the wizard | Do not create that helper. A wizard-made room has its own kill switch, Engine Enabled (switch.crop_steering_engine_enabled); the helper would be a second one that does nothing. The card came from a controller started before setup, still reporting its built-in default name. Update to integration 2.19.2. On older versions it clears by itself once the controller has picked the room up (engine and switches OFF, then restart the app). Only a room that really is gated by that helper (an install from before the wizard) should recreate it. |
| Last irrigation shows a time, but shots are 0 and water is 0.0 L | Before controller 0.16.2 the moment a room was switched on was shown as an irrigation. Update; it reads unknown until water has really been delivered. |
| Alert: probe dead - blind schedule, but the sensor shows a value | The controller treats a reading that has not changed for 20 minutes as a dead probe, and waters that zone on a timed safety schedule instead (a shot every 90 minutes by default, within the daily cap). This is deliberate: a probe pulled out of its cube keeps reporting a steady number, and the plant it left behind still needs water. It also happens to a probe sitting in a cube with no plant in it, or pegged at its maximum in a soaked one, because nothing is drinking and the number never moves. Expect it on a bench test; with a plant drawing water it clears by itself. |
| Sidebar shows Controller: not reported (or Integration: not reported) | That half is older than the version that started reporting (controller 0.16.1, integration 2.19.1), or, for the controller, it is not running. Update it, or start the controller app and wait one loop (up to a minute). If the two numbers are not a pair named together in the changelog, update the older half. |
| Notification: Irrigation BLOCKED - plumbing and switches disagree | The room's declared plumbing and its mapped switches contradict each other (it says it has a pump and none is mapped, or the other way round), so the controller will not water it. Nothing is wrong with the hardware. Fix it in Rooms & setup: map the missing switch, or change the plumbing to what the room really has. The hold clears by itself once the new setup is adopted (kill switch and hardware OFF, as for any setup change). |
| Setup refuses to save: The plumbing for this room is set to […], but no pump switch is chosen | You said the room has a pump (or a main-line valve) and did not choose one, or cleared one that the layout needs. Choose the switch, or change the plumbing if the room really has none. |
| Integration shows 'Failed to set up' after the wizard | On Home Assistant older than 2026.5, update to integration 2.18.1. Earlier versions called a sidebar helper that only exists from 2026.5, so the entry never loaded (no entities, no dashboard). Nothing needs re-entering: reload the integration after updating. |
| Lights-on / lights-off hours are not what setup was told | Before 2.18.1 the wizard's hours were stored and ignored, and the entities started at 12 and 0. A NEW room on 2.18.1 uses what you typed. An existing room keeps whatever its entities hold: set number.crop_steering_<room>lights_on_hour / _off_hour once. |
| Configure > Edit parameters saved, nothing changed | Update to 2.18.1. Earlier versions saved the edit and each setting then restored its old value. The number entities on the dashboard always worked and still do. |
| A sensor or pump cannot be removed in Configure | Update to 2.18.1. Earlier versions put a cleared field straight back; a mapping could only be swapped for another. |
| Mapping saved but controller has old data | Compare setup revision with controller acknowledgement. Wait for rediscovery and inspect app logs. |
| Room/zone disappeared | Check Rooms & setup for archived entries. Restore the same ID; do not reuse IDs for different equipment. |
| No recorded EC line | Confirm mapped EC entities are recorded in HA Recorder and have data in the selected time range. A target line is not a sensor history. |
| Shot volume disagrees with observation | Verify litres per plant, plant count, drippers/plant and actual L/h; run a catch test. Inspect duration caps and physical pressure/flow. |
| Source code change did not reach controller | Use Update/Rebuild. Restarting an existing container keeps its old image. |
| Hardware fault remains latched | All implicated engines and shared hardware must be OFF before recovery; inspect the actual fault first. |
| Embedded theme does not match | Use the integration's same-origin sidebar and Follow Home Assistant. Cross-origin standalone pages cannot read parent theme variables. |
| Live connection failed | Reauthenticate HA or configure the explicit connection in Settings. The app does not silently switch to demo data. |
Use INSTALL.md for repository links and commissioning steps. The public repository must contain the intended revision before guided installation can obtain it. Browser or unit-test success does not prove that an older deployed image has changed.