home-assistant/core · error · ConfigEntryError

Could not find Azure Data Explorer database or table

Error message

Could not find Azure Data Explorer database or table

What it means

Raised as ConfigEntryError from the azure_data_explorer integration when adx.test_connection() (a Kusto query against the configured database/table) throws KustoServiceError — the Azure Data Explorer cluster accepted the connection attempt but the query/service failed: database or table not found, bad cluster URL, or a service-level error. Setup stops permanently (no retry) until the user fixes the config.

Source

Thrown at homeassistant/components/azure_data_explorer/__init__.py:78

    Adds an empty filter to hass data.
    Tries to get a filter from yaml, if present set to hass data.
    """
    if DOMAIN in yaml_config:
        hass.data[DATA_COMPONENT] = yaml_config[DOMAIN].pop(CONF_FILTER)
    else:
        hass.data[DATA_COMPONENT] = FILTER_SCHEMA({})

    return True


async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Do the setup based on the config entry and the filter from yaml."""
    adx = AzureDataExplorer(hass, entry)
    try:
        await adx.test_connection()
    except KustoServiceError as exp:
        raise ConfigEntryError(
            "Could not find Azure Data Explorer database or table"
        ) from exp
    except KustoAuthenticationError:
        return False

    entry.async_on_unload(adx.async_stop)
    await adx.async_start()
    return True


async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Unload a config entry."""
    return True


class AzureDataExplorer:
    """A event handler class for Azure Data Explorer."""

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Verify the cluster URI, database, and table names in the config entry exactly match Azure (test with Kusto Explorer or the Kusto CLI: .show databases / table exists).
2. Create the target table if it does not exist yet, or point the integration at an existing one.
3. Ensure the app registration/user has at least Database User on the target database.
4. Re-run setup/reconfigure after fixing; ConfigEntryError will not retry on its own.

from azure.kusto.data import KustoClient, KustoConnectionStringBuilder

async def kusto_target_ok(cluster_url: str, database: str, table: str) -> bool:
    kcb = KustoConnectionStringBuilder.with_aad_device_authentication(cluster_url)
    client = KustoClient(kcb)
    result = client.execute(database, f".show table {table} schema")
    return not result.errors

from azure.kusto.data.exceptions import KustoServiceError, KustoAuthenticationError

try:
    await adx.test_connection()
except KustoServiceError as err:
    raise ConfigEntryError("Could not find Azure Data Explorer database or table") from err
except KustoAuthenticationError:
    return False  # auth issue: surface re-auth instead

When it happens

Trigger: test_connection() executes a sample query and Kusto returns an error entity: database name typo'd, table not created yet, cluster URI wrong (e.g. https://cluster.region.kusto.az ure.com mis-typed), or insufficient database-level permission producing a service error.

Common situations: Table not yet created by the user's setup script; database name case/typo; cluster URL from a different Azure environment; principal lost Reader/Database User rights.

Related errors

• Credential is already linked to a user
• System generated users cannot disable multi-factor auth modu
• Invalid authentication
• Cannot delete credential in use by integration {entry.domain
• Authentication failed, please check credentials

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/d605985a86d1efcd. Report an issue: GitHub.