Config Entries are configuration data that are persistently stored by Home Assistant. A config entry is created by a user via the UI. The UI flow is powered by a config flow handler as defined by the component. Config entries can also have an extra options flow handler, also defined by the component.
|not loaded||The config entry has not been loaded. This is the initial state when a config entry is created or when Home Assistant is restarted.|
|loaded||The config entry has been loaded.|
|setup error||An error occurred when trying to set up the config entry.|
|setup retry||A dependency of the config entry was not ready yet. Home Assistant will automatically retry loading this config entry in the future. Time between attempts will automatically increase.|
|migration error||The config entry had to be migrated to a newer version, but the migration failed.|
|failed unload||The config entry was attempted to be unloaded, but this was either not supported or it raised an exception.|
Setting up an entry
During startup, Home Assistant first calls the normal component setup,
and then call the method
async_setup_entry(hass, entry) for each entry. If a new Config Entry is
created at runtime, Home Assistant will also call
async_setup_entry(hass, entry) (example).
If a component includes platforms, it will need to forward the Config Entry to the platform. This can be done by calling the forward function on the config entry manager (example):
For a platform to support config entries, it will need to add a setup entry method (example):
Components can optionally support unloading a config entry. When unloading an entry, the component needs to clean up all entities, unsubscribe any event listener and close all connections. To implement this, add
async_unload_entry(hass, entry) to your component (example).
For each platform that you forwarded the config entry to, you will need to forward the unloading too.
If you need to clean up resources used by an entity in a platform, have the entity implement the
Removal of entries
If a component needs to clean up code when an entry is removed, it can define a removal method: