# 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
```yaml
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
```bash
# HA OS
ha core check
# Docker
docker exec homeassistant python -m homeassistant --config /config --script check_config
```