Troubleshooting Findings

Troubleshooting Findings

This page explains every finding the built-in Troubleshoot step (and the offline diagnostics triage) can raise. Each cover's options flow has a Troubleshoot entry that runs a read-only rules engine over the current config and the last diagnostics snapshot; every issue it reports links here at a stable per-finding anchor.

The same rule table drives both surfaces — the in-product step and the offline scripts/triage_json.py run against a downloaded diagnostics file — so a finding you see in Home Assistant reads identically to the one a maintainer sees when triaging your issue. If a symptom has no matching finding here, that is the signal that a new rule is worth adding: see Developer Triage Rules.

Severity legend: ⚠️ warning · ℹ️ info · 🛑 critical.

---

Custom safety bypass

What it means. A custom-position slot is set to safety priority (100). At that priority the slot bypasses the automatic-control toggle, manual override, and the start/end time window — it can move the cover even when automatic control is OFF and outside your schedule.

Why it fires. You configured a custom position slot with a trigger and a position claim, and its priority equals 100.

What to change. If that slot is meant to be a normal preference rather than a safety action (storm shutter, privacy lockout), lower its priority below 100 so it respects the gates. Leave it at 100 only when you genuinely want it to act unconditionally.

See Custom Position.

Higher priority won

What it means. A handler that outranks solar tracking won the update cycle, so the solar handler never set a position.

Why it fires. The decision trace shows a non-solar handler matched, and its configured priority is above the solar handler's.

What to change. This is often correct (weather safety or a manual override should win). If solar tracking should have decided instead, review the handler priority ladder and lower the winning handler or raise solar.

See How It Decides.

Time window suspect

What it means. The active-window schedule looks misconfigured, so the cover may never track.

Why it fires. Either the start bound is driven by a sun sensor (sensor.sun_next_*) or the window is inverted (start time after end time) with real clock times.

What to change. Review the start and end times, or the sun-based start entity, so the tracking window is a sensible interval.

See Automation.

Climate temp none

What it means. Climate mode is on but the inside temperature is unavailable, so climate decisions cannot run.

Why it fires. The diagnostics report inside_temperature as None while climate mode is enabled.

What to change. Check the configured temperature sensor — it may be unavailable, misconfigured, or reporting a non-numeric state.

See Climate.

Summer wont close

What it means. It is summer with presence detected and the blind is not transparent, yet the climate handler did not close it.

Why it fires. Summer and presence conditions are both true, the blind is not marked transparent, and the climate step did not match in the decision trace.

What to change. Review the summer-close conditions and temperature thresholds so the cover closes when you expect it to.

See Climate Mode.

Presence defaults true

What it means. Climate mode is on but no presence entity or template is set, so presence defaults to always-present.

Why it fires. Climate mode is enabled and neither a presence entity nor a presence template is configured.

What to change. Add a presence sensor or template if occupancy should gate climate control. If you intend climate to run regardless of occupancy, no change is needed.

See Climate.

Cloud or semantics

What it means. More than one low-light input is configured; they combine with OR, so any one of them tripping suppresses tracking.

Why it fires. Two or more of the lux / irradiance / weather inputs are configured at once.

What to change. Confirm the OR semantics are what you want. If a single input tripping should not suppress tracking, remove the redundant inputs or adjust their thresholds.

See Weather Safety.

Cover not ready

What it means. A configured cover reported no capabilities — it is unavailable.

Why it fires. During the capability probe the cover entity returned no feature set (None), which usually means it is unavailable in Home Assistant.

What to change. Check the cover device and its integration; the entity must be available for the integration to read its features and drive it.

See Cover Types.

Entity unavailable

What it means. A configured sensor or cover entity is currently unavailable, so the integration cannot read its state.

Why it fires. A local sensor, building-profile sensor, or bound cover reported unavailable in the last snapshot.

What to change. This is an HA-side condition — check the underlying device or sensor. No options step fixes an unavailable entity.

See Troubleshooting.

Min floor bypassed

What it means. A minimum-position floor is set, but one or more fixed positions fall below it.

Why it fires. The sunset position or a custom-slot position is lower than the configured minimum position, so those values undercut the floor.

What to change. Reconcile the values — either raise the offending positions to the floor or lower the minimum position.

See Position.

Enable min backwards

What it means. A minimum position is set but enforce minimum only while sun tracking is off, so the floor applies at all times.

Why it fires. enable_min_position is False (the flag reads backwards: False = always enforce) while a positive minimum position is set.

What to change. Confirm the always-enforce behaviour is intended. If the floor should apply only during sun tracking, flip the toggle on.

See Position.

Tracking window truncated

What it means. The maximum tracking elevation is low, so sun tracking stops once the sun climbs above it — the active tracking window is truncated.

Why it fires. The configured max_elevation is 25° or below.

What to change. Raise the maximum tracking elevation if the cover should keep tracking a higher sun. Leave it low only when you deliberately want tracking to stop at a modest sun height.

See Sun Tracking.

Geometry near binary

What it means. The shaded distance is very small, so the shade sweeps the window in just a couple of steps and the resolved position is nearly all-or-nothing.

Why it fires. distance_shaded_area is below 0.75 m.

What to change. Increase the shaded distance if you want finer intermediate positions. A tiny distance is legitimate for a shallow reveal, but expect coarse steps.

See Geometry.

Special position delta bypass

What it means. The default position is a special endpoint value (0% or 100%) paired with a movement delta wide enough to skip fine intermediate moves, so the cover jumps between endpoints.

Why it fires. default_percentage is 0 or 100 and delta_position is greater than 5%.

What to change. Lower the movement delta for smoother stepping, or confirm the jump-to-endpoint behaviour is what you want.

See Behavior.

Custom above manual

What it means. A custom-position slot has a priority above manual override (80) but below the safety ceiling (100), so it overrides a manual move without acting as a safety slot.

Why it fires. A configured custom slot's priority sits strictly between 80 and 100.

What to change. Lower the slot below 80 if a manual override should win instead. This is informational — it may be exactly what you intend.

See Custom Position.

Glare zone never fires

What it means. A glare zone sits entirely beyond the shaded distance, so the glare handler can never act on it.

Why it fires. The zone's near edge (y − radius) is farther from the window than the configured shaded distance.

What to change. Move the zone closer to the window or increase the shaded distance so the zone falls within reach.

See Glare Zones.

Position matching off

What it means. A manual override is active and position matching is off, so the integration will not clear the override when the cover returns to the calculated position.

Why it fires. The control status is manual_override and enable_position_matching is False.

What to change. Enable position matching if the override should self-clear once the cover reaches the position the integration would have chosen. Leave it off if you prefer overrides to persist until their timeout.

See Position Matching.

Dry run left on

What it means. Dry-run mode is on: commands are logged but never sent, so the cover never actually moves.

Why it fires. debug_config.dry_run is True in the diagnostics.

What to change. Turn dry-run off in the debug options once you are done testing. Leave it on only while you are inspecting decisions without moving hardware.

See Debug & Diagnostics.

Override blocked auto off

What it means. Automatic control is off for this cover, so the integration will not move it and overrides cannot act.

Why it fires. The control status is automatic_control_off.

What to change. Turn automatic control back on when you want tracking to resume. This is informational — the cover is deliberately parked.

See Troubleshooting.

Azimuth fov mismatch

What it means. The sun is above the horizon but outside this window's sun acceptance angle, so only the default handler ran and no sun tracking happened.

Why it fires. sun_validity.in_fov is false while valid_elevation is true, and the decision trace shows the default handler won the cycle.

What to change. Check the window azimuth and sun acceptance angle settings if the sun should be reaching this window. If the window genuinely does not face the sun at this time, no change is needed.

See Geometry.

Endpoint chase

What it means. A cover gave up reaching its commanded target after repeated retries — it keeps settling short of the requested position.

Why it fires. A cover's command state shows gave_up true after exhausting its retries.

What to change. Check the cover's travel calibration or position feedback; a cover that never reports reaching its target will keep being nudged until it gives up.

See Position.

Cover feature mismatch

What it means. A bound cover does not expose an axis this cover type requires — for example a venetian or tilt type bound to an entity with no set_tilt_position — so the integration cannot drive it correctly.

Why it fires. The cover type's declared axis requirements list a capability the entity's feature set (and its fallbacks) does not satisfy.

What to change. Pick a cover entity that exposes the required axis, or change this instance's cover type to one that matches the entity's capabilities. A position-only cover reached via open/close is not flagged — only a genuinely missing axis is.

See Cover Types.

Skip service call failed

What it means. The last cover command was skipped because the service call itself failed.

Why it fires. The most recent skipped action recorded the reason service_call_failed. The finding includes how long ago it happened.

What to change. Check the cover integration and the Home Assistant log for the underlying error — the service raised rather than the integration choosing to skip.

See Covers & Device.

Skip no capable service

What it means. The last cover command was skipped because no capable service was found to move the cover.

Why it fires. The most recent skipped action recorded the reason no_capable_service — the entity exposes neither set_cover_position nor an open/close pair the integration can use.

What to change. Bind a cover that exposes the position or open/close services the integration needs, or pick a cover type matching the entity's capabilities.

See Covers & Device.

Skip cover unavailable

What it means. The last cover command was skipped because the cover was unavailable at the time.

Why it fires. The most recent skipped action recorded the reason cover_unavailable. The finding includes how long ago it happened.

What to change. Check the device — it was offline when the integration tried to move it. A one-off during a restart is harmless; a persistent skip points at a flaky device.

See Troubleshooting.

Stale version

What it means. A newer release of the integration is available than the one you are running.

Why it fires. A latest_version was supplied to the triage run and it parses as a newer CalVer than the running integration_version. This finding only appears when the offline triage is given --latest-version; the in-product step does not fetch release data.

What to change. Update the integration through HACS to pick up the latest fixes.

See Installation.

Mixed temp units

What it means. The inside and outside temperature sensors report different units of measurement — one in °C, the other in °F. Adaptive Cover Pro compares the raw numbers and does not convert between units, so every climate comparison between them is wrong.

Why it fires. The inside temperature sensor's unit_of_measurement differs from the outside temperature sensor's. This is critical because a °F-vs-°C mismatch silently corrupts summer/winter and threshold decisions.

What to change. Set both temperature sensors to the same unit — both °C or both °F — in Home Assistant, or pick sensors that already agree. The units must match for the comparison to mean anything.

See Climate Control.

Endpoint position not tracking

What it means. "Use open/close at endpoints" sent open_cover or close_cover for a 0%/100% target, and the entity itself reports the matching mechanical stop (open or closed), but its current_position attribute never followed — it's still off by more than the position tolerance. This is typical of one-way RF bridges (assumed_state: true, e.g. Bond → Somfy RTS/RMS) that echo set_cover_position correctly but don't update position from a raw open/close command.

Why it fires. The cover's command state shows a waiting 0%/100% target that has not given up (gave_up is not true — distinct from Endpoint chase, which requires it), the entity's HA state already claims the corresponding open/closed stop, current_position sits outside tolerance of that target, and the entity does expose set_cover_position as a fallback.

What to change. Turn off Use open/close at endpoints so the integration sends set_cover_position at 0% and 100% too, instead of the open/close commands this cover doesn't reflect in its reported position.

See Position.

Weather override inverted

What it means. Weather override is a safety retraction — when wind or rain shows up, the cover is supposed to move somewhere it won't be damaged. As configured, yours moves further deployed than its own default position, so bad weather will put the cover out rather than pull it in.

The trap is that 0% is not universally "safe". The override position's schema default is 0, which is the retracted endpoint for an awning but the deployed endpoint for a blind, venetian, or tilt cover. Leaving it at 0 on a blind therefore asks for a fully-closed blind in a storm.

Why it fires. Weather handling is enabled with at least one trigger source, Use override as minimum is off, and the override position is more deployed than the default position measured on the cover's own axis polarity. For an awning "more deployed" means a higher percentage; for a blind/venetian/tilt it means a lower one.

What to change. Set the weather override position to your cover's retracted end — 100% for a blind, venetian, or tilt cover; 0% for an awning. The finding tells you which one applies to yours. If you genuinely want the override to act as a floor rather than a target, turn on Use override as minimum instead, which suppresses this check.

See Weather & Safety.

Solar internal cover weak rejection

What it means. You described this cover as mounted inside the glass, and the shade you picked rejects comparatively little solar heat. Sunlight has already crossed the glazing before it reaches an internal fabric, so most of the energy the fabric absorbs is re-radiated into the room rather than back outside. The finding puts a number on that: the estimated share of incident solar energy the window still admits with the cover fully closed, next to what the same shade would admit if it hung outside.

This is informational, not a misconfiguration. Nothing in the integration behaves differently because of it, and no cover moves.

Why it fires. The optional solar properties description is enabled, Cover mounting side is set to Internal, and the resulting fully-closed g-value — either the preset for your (side, shade) pair or your own Total solar transmittance (g) override — is above 0.40.

What to change. Nothing, unless you are choosing between mounting options. If you are, an external cover of the same shade typically rejects two to three times more solar heat than an internal one. If your fabric's real g-value is better than the preset assumes, enter it in Total solar transmittance (g) and the finding will reflect the number you supplied.

When you do supply that number yourself, the finding drops the shade word and the external-cover comparison. Both are read off the preset table, and your figure replaced it — comparing your measured fabric against a band it never came from would be misleading.

Every value in this finding is an estimate drawn from published EN ISO 52022 / EN 13363 bands, not a measurement of your hardware. Treat it as an order of magnitude.

See Sun Tracking, where the geometry fields these options sit alongside are documented.