Troubleshoot cluster configuration
Note
We will retire Azure HDInsight on AKS on January 31, 2025. Before January 31, 2025, you will need to migrate your workloads to Microsoft Fabric or an equivalent Azure product to avoid abrupt termination of your workloads. The remaining clusters on your subscription will be stopped and removed from the host.
Only basic support will be available until the retirement date.
Important
This feature is currently in preview. The Supplemental Terms of Use for Microsoft Azure Previews include more legal terms that apply to Azure features that are in beta, in preview, or otherwise not yet released into general availability. For information about this specific preview, see Azure HDInsight on AKS preview information. For questions or feature suggestions, please submit a request on AskHDInsight with the details and follow us for more updates on Azure HDInsight Community.
Incorrect cluster configuration may lead to deployment errors. Typically those errors occur when incorrect configuration provided in ARM template or input in Azure portal, for example, on Configuration management page.
Note
Those errors will have reason starting with "User." prefix.
Example configuration error:
The following table provides error codes and their description to help diagnose and fix common errors.
Configuration errors
| Error code | Description |
|---|---|
| User.TrinoError | Trino process startup fails with generic error. Verify trino specific configuration files in Service configuration profile. |
| User.Configuration.TrinoError | Trino process startup fails with application configuration error. Verify trino specific configuration files in Service configuration profile. |
| User.Configuration.FileForbidden | Changes to some trino configuration files aren't allowed. |
| User.Configuration.ParameterForbidden | Changes to some trino configuration parameters aren't allowed. |
| User.Configuration.InvalidComponent | Invalid service component specified. For more information, see Service configuration profile. |
| User.Configuration.MiscFile.InvalidName | Invalid miscellaneous fileName. For more information, see Miscellaneous files. |
| User.Configuration.MiscFile.InvalidPath | Miscellaneous file path is too long. |
| User.Configuration.MiscFile.NotFound | Found MISC tag without corresponding file in miscellaneous files configuration. For more information, see Miscellaneous files. |
| User.Configuration.MiscFile.DuplicateName | Duplicate fileName value found in Miscellaneous files configuration section. |
| User.Configuration.MiscFile.DuplicatePath | Duplicate path value found in Miscellaneous files configuration section. |
| User.Configuration.FormatError | Malformed service configuration, content/values properties used in wrong sections. For more information, see Service configuration profile. |
| User.Configuration.HiveMetastore.MultiplePasswords | Multiple passwords specified in catalogOptions.hive catalog. Specify one of two properties either metastoreDbConnectionPasswordSecret or metastoreDbConnectionPassword. |
| User.Configuration.HiveMetastore.PasswordRequired | Password required for catalogOptions.hive catalog. Specify one of two properties either metastoreDbConnectionPasswordSecret or metastoreDbConnectionPassword. |
| User.Secrets.Error | Misconfigured secrets or permissions in Azure KeyVault. |
| User.Secrets.InvalidKeyVaultUri | Missing Azure Key Vault URI in secretsProfile. |
| User.Secrets.KeyVaultUriRequired | Missing Azure Key Vault URI in secretsProfile. |
| User.Secrets.DuplicateReferenceName | Duplicate referenceName found in secretsProfile. |
| User.Secrets.KeyVaultObjectUsedMultipleTimes | Same key vault object/version used multiple times as different references in secrets list in secretsProfile. |
| User.Secrets.NotSpecified | Found SECRET_REF tag without corresponding secret object in secretsProfile. |
| User.Secrets.NotFound | Specified Key Vault object in secretsProfile not found in KeyVault. Verify name, type and version of the object. |
| User.Plugins.Error | Misconfigured plugins or permissions in storage account. |
| User.Plugins.DuplicateName | Duplicate plugin name used in cluster configuration userPluginsSpec. |
| User.Plugins.DuplicatePath | Duplicate plugin path used in cluster configuration userPluginsSpec. |
| User.Plugins.InvalidPath | Malformed storage URI for a plugin. |
| User.Plugins.PathNotFound | Specified path for a plugin not found in storage account. |
| User.Telemetry.InvalidStoragePath | Malformed storage URI in userTelemetrySpec. |
| User.Telemetry.HiveCatalogNotFound | Nonexistent Hive catalog specified as target for telemetry tables in userTelemetrySpec. |
| User.CatalogOptions.HiveCatalogNotFound | Hive catalog not found in trino catalogs Service configuration profile for a given catalogOptions.hive configuration. For more information, see Hive metastore. |
System errors
Some of the errors may occur due to environment conditions and be transient. These errors have reason starting with "System." as prefix. In such cases, try the following steps:
- Collect the following information:
- Azure request CorrelationId. It can be found either in Notifications area; or under Resource Group where cluster is located, on Deployments page; or in az command output.
- DeploymentId. It can be found in the Cluster Overview page.
- Detailed error message.
- Contact support team with this information.
| Error code | Description |
|---|---|
| System.DependencyFailure | Failure in one of cluster components. |