mes_skills/skills/infra/ha-log-investigator/references/ha-common-errors.md

Erreurs Home Assistant fréquentes — Catalogue documenté

Intégrations

Platform X not ready

• Cause : Le service distant n'est pas encore accessible au démarrage de HA
• Solution : Ajouter initial_state: false ou augmenter scan_interval. Vérifier la connectivité réseau.
• Doc : https://www.home-assistant.io/integrations/#configuration-check

Error while setting up integration X

• Cause : Credentials invalides, service inaccessible, config incorrecte
• Solution : Supprimer et reconfigurer l'intégration via Paramètres → Intégrations
• Doc : https://www.home-assistant.io/docs/configuration/

Integration X already exists

• Cause : Intégration configurée à la fois en YAML et en UI
• Solution : Retirer la config YAML si l'intégration supporte l'UI (voir doc de l'intégration)
• Doc : https://www.home-assistant.io/docs/configuration/packages/

Deprecated

• Cause : Usage d'une API ou d'un format deprecated
• Solution : Consulter les release notes de la version HA installée
• Doc : https://www.home-assistant.io/blog/ (chercher la version concernée)

---

Entités

unavailable

• Cause possible 1 : Appareil physique hors ligne
• Cause possible 2 : Intégration en erreur
• Cause possible 3 : Template invalide
• Diagnostic : Vérifier les logs pour le nom de l'entité

unknown

• Cause : L'entité existe mais n'a pas encore reçu de valeur (souvent au démarrage)
• Normal : Peut disparaître après quelques secondes/minutes
• Problématique : Si persiste, vérifier la config

Template error

Error rendering template: UndefinedError: 'sensor.xyz' is undefined

• Solution : Utiliser states('sensor.xyz') au lieu de states.sensor.xyz.state (plus robuste)
• Doc : https://www.home-assistant.io/docs/configuration/templating/

---

Base de données / Recorder

Database disk usage: X MB

• Cause : Base de données SQLite trop volumineuse
• Solution : Configurer recorder avec purge_keep_days et exclure les entités à haute fréquence

recorder:
  purge_keep_days: 7
  exclude:
    entity_globs:
      - sensor.*_signal_strength
      - sensor.*_rssi

• Doc : https://www.home-assistant.io/integrations/recorder/

---

Lovelace / Dashboards

Custom card non chargée

Custom element doesn't exist: custom-card-name

• Cause : La ressource custom card n'est pas déclarée ou le fichier est manquant
• Solution : Paramètres → Tableaux de bord → Ressources → Ajouter le JS
• Doc : https://www.home-assistant.io/dashboards/dashboards/

Entité manquante dans dashboard

Entity not available: sensor.xyz

• Solution : Vérifier que l'entité existe (États dans les outils de développement), corriger le nom dans la carte

---

Réseau / SSL

SSL CERTIFICATE_VERIFY_FAILED

• Cause : Certificat auto-signé ou expiré
• Solution : Vérifier verify_ssl: false pour les connexions internes (non recommandé en prod), ou renouveler le certificat
• Doc : https://www.home-assistant.io/docs/configuration/securing/

Connection refused / Cannot connect to host

• Cause : Service distant éteint ou port bloqué par firewall
• Diagnostic : ping, telnet HOST PORT depuis le host HA

---

YAML / Configuration

Indentation YAML incorrecte

• Erreur : mapping values are not allowed here
• Outil : https://yaml-online-parser.appspot.com/
• Conseil : Utiliser 2 espaces, jamais de tabulations

!secret not found

• Cause : La clé référencée n'existe pas dans secrets.yaml
• Solution : Ajouter la clé dans /config/secrets.yaml

Config check

# HA OS
ha core check
# Docker
docker exec homeassistant python -m homeassistant --config /config --script check_config