Troubleshooting
Applies to release 3.18.1 · View source at the tag · Markdown
A notification or Repairs card that ends with a code such as CS-101: look the code up in Error codes (the same list is in the dashboard under Settings › Help) for what it means, what happens to watering meanwhile, the likely causes and what to do.
Start with Settings › System status: it lists every mapped device as online, offline or silent, and each room's controller heartbeat (System status).
| 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 active at the next local lights-on after arming. Arming never enables the engine. If the controller's heartbeat or a probe was stale at lights-on, or Home Assistant was restarting, it activates at the first minute it can; Repairs shows grow strategy plan has not moved on to today with the reason until then. |
| Active plan is held or in error | Repairs shows grow strategy plan is holding irrigation with the reason. While held, the controller still waters the overnight emergency, watchdog and minimum-daily shots; only the plan's steering waits. Restore valid fresh data; use disarm for an explicit return to manual targets at the next lights-on. Do not bypass the required-plan latch. |
| Setup refuses a zone change: The grow strategy plan is armed… | A plan that is armed or running manages a fixed set of zones. Disarm it (Irrigation › Grow plan & presets), wait for it to return to draft at the next lights-on, change the zones, then use Update zones from setup and arm it again. |
| 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. The controller reads every probe, the feed probes and the sump plug through the same table (crop-steering-engine/src/crop_steering_engine/defaults.py, UNITS): a probe with no unit, or one the table does not know, is read as before (% for moisture, mS/cm for EC, W for power) while its number is plausible, and the log says so once. A feed EC probe in ppm or ppt is read as mS/cm while its number is plausible, as it always was, so the source-water gate never holds for its unit. A moisture probe whose unit can't be read as % and whose number is outside 0 to 100 is set aside: the zone waters as for a dead probe and the notification says why (CS-503). |
| 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 Equipment › Setup: pumps & valves (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. |
| Setup stops with Home Assistant is still running Crop Steering X, but Y is installed | HACS replaces the files; Home Assistant goes on running the code it loaded when it started. Restart Home Assistant, then add Crop Steering again. The first setup screen, the add-a-room screen and the Configure menu all show the version that is actually running (from the release that carries this change). If a setup screen shows no version at all, the code running is older than that: restart Home Assistant before going any further. A room set up on stale code keeps whatever that code created, entity ids included, and those are for life: the symptoms are a controller reporting settings missing, running on built-in values (CS-402; older controllers: Setpoint entities missing), a sidebar reading Integration: not reported, and entities called number.<your device>_crop_steering_…. The way out is to delete the integration, restart Home Assistant, and set it up again. |
| Repairs says N setting(s) are not where the controller looks for them (CS-605) | The controller, the dashboard and the MCP tools find a setting by its exact entity id (number.crop_steering_zone_1_plant_count), and the listed ones are registered under another id, so the controller runs on its built-in defaults for them and reports settings missing, running on built-in values (CS-402; older controllers: Setpoint entities missing). Keep the engine off. One or two listed: an entity id was edited; change it back under Settings → Devices & services → Entities → the entity → the cog. Nearly all listed: the room was created while Home Assistant was still running an older integration (see the row above); delete the entry, restart Home Assistant, add it again. The card clears by itself, and nothing is renamed for you. |
| 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 (CS-601), 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: moisture reading hasn't changed (CS-101) (older controllers: 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. A room with nothing growing can have its Room Active switch turned off, which stops its notifications. See CS-101. |
| 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: plumbing and switches disagree, not watering (CS-202) (older controllers: 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 Equipment › Setup: pumps & valves: 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 Equipment › Setup: pumps & valves 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. |
| A room holds with source-water EC band unreadable (…) — holding (fail-closed) (or the pH equivalent) | One of the room's irrigation pH/EC limit numbers (number.crop_steering_<prefix>irrigation_{ec,ph}_{min,max}) reads unavailable, unknown or not a number. Check the integration loaded and the named number has a value. The hold lifts on the first pass where it reads again (Upgrade to 3.18: the plan). |
| Shots held with feed probe calibration in progress | A feed pH/EC calibration session is open and the room has a feed band for that probe. Finish or abandon the session; everything resumes within 30 minutes of the last capture (Calibration). |
| A prime or pump calibration is refused | A run does not start while the kill switch is off, a shot is in flight, a batch or another session holds the room, or CS-301 is latched (Calibration). |
| CS-214: a zone waited for the pump, or needs more than it gives | Water continues. Measure and correct the pump's max_flow_lph, check the zone's plant count, drippers and dripper flow, or spread the shots (Water supply). |
| CS-318: the meter saw less water than a shot counted | Water continues. Check the zone's line, filter and drippers, a half-closed hand valve, the dripper settings, and the meter's unit and reporting (Water supply). |
| CS-319: the meter counted water with no shot running | Nothing is switched off. Check for a valve stuck open or leaking, a broken line after the meter, hand watering or an automation opening a valve on the same line (Water supply). |
| No queue, no CS-214, no flow checks | No supply is saved, or the zone has no meter in it. sensor.crop_steering_supply_config must exist and not be unavailable (Water supply). |
| A zone set to Watering by: timer does not water | Check the zone is in an active program with a window that covers now, and that sensor.crop_steering_<prefix>timers_config is not unavailable (Timer programs). |
| The event journal is unavailable | Check the Home Assistant log for Event journal unavailable (…journal.db), usually disk space or permissions on <config>/crop_steering/. Watering is not affected (History). |
| An alert stays in the inbox | It stays open until it clears, is acknowledged or its notification is dismissed. Any signed-in user can acknowledge it (Alerts). |
Use Installation, upgrade and rollback 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.