{"record":{"id":"5e86c57d6cc1a8e6","repo":"dotnet/orleans","slug":"invalid-nameof-adonetclusteringclientoptions-va","errorCode":null,"errorMessage":"Invalid {nameof(AdoNetClusteringClientOptions)} values for {nameof(AdoNetClusteringTable)}. {nameof(options.Invariant)} is required.","messagePattern":"Invalid (.+?) values for (.+?)\\. (.+?) is required\\.","errorType":"validation","errorClass":"OrleansConfigurationException","httpStatus":null,"severity":"error","filePath":"src/AdoNet/Orleans.Clustering.AdoNet/Options/AdoNetClusteringClientOptionsValidator.cs","lineNumber":24,"sourceCode":"{\n    /// <summary>\n    /// Validates <see cref=\"AdoNetClusteringClientOptions\"/> configuration.\n    /// </summary>\n    public class AdoNetClusteringClientOptionsValidator : IConfigurationValidator\n    {\n        private readonly AdoNetClusteringClientOptions options;\n\n        public AdoNetClusteringClientOptionsValidator(IOptions<AdoNetClusteringClientOptions> options)\n        {\n            this.options = options.Value;\n        }\n\n        /// <inheritdoc />\n        public void ValidateConfiguration()\n        {\n            if (string.IsNullOrWhiteSpace(this.options.Invariant))\n            {\n                throw new OrleansConfigurationException($\"Invalid {nameof(AdoNetClusteringClientOptions)} values for {nameof(AdoNetClusteringTable)}. {nameof(options.Invariant)} is required.\");\n            }\n\n            if (string.IsNullOrWhiteSpace(this.options.ConnectionString) == (this.options.DataSource is null))\n            {\n                throw new OrleansConfigurationException($\"Invalid {nameof(AdoNetClusteringClientOptions)} values for {nameof(AdoNetClusteringTable)}. Configure exactly one of {nameof(options.ConnectionString)} or {nameof(options.DataSource)}.\");\n            }\n        }\n    }\n}","sourceCodeStart":6,"sourceCodeEnd":33,"githubUrl":"https://github.com/dotnet/orleans/blob/fca799fa70ecb6ad975224271703ca43221f58de/src/AdoNet/Orleans.Clustering.AdoNet/Options/AdoNetClusteringClientOptionsValidator.cs#L6-L33","documentation":"Thrown by AdoNetClusteringClientOptionsValidator.ValidateConfiguration when the configured Invariant (the AdoNet provider invariant name, e.g. 'System.Data.SqlClient' or 'Microsoft.Data.SqlClient') is null or whitespace. The invariant identifies which ADO.NET database provider to load, so a missing invariant makes the clustering table unusable; the validator fails fast at silo/client startup with an OrleansConfigurationException.","triggerScenarios":"Produced at startup when AdoNetClusteringClientOptions.Invariant is unset and the clustering client options validator runs. Triggered by a missing/incomplete 'Invariant' in the AdoNet clustering configuration section, a typo, or reading the value from a config source that returned empty.","commonSituations":"Appsettings section for clustering missing the Invariant field; copied a partial config block; environment-specific config that omits the invariant; switching DB providers but forgetting to update the invariant string.","solutions":["Set Invariant to the correct ADO.NET provider invariant for your database (e.g. 'Microsoft.Data.SqlClient' for SQL Server, 'Npgsql' for PostgreSQL, 'MySql.Data.MySqlClient' for MySQL).","Make sure the corresponding DbProviderFactory is registered (AdoNetInvariants.RegisterProvider / the provider package is referenced).","Validate the clustering config section is being read by the correct named options.","Confirm the DB provider package is installed so the invariant resolves at runtime."],"exampleFix":"// before\nbuilder.UseAdoNetClustering(options =>\n{\n    options.ConnectionString = \"Server=...;Database=Orleans;...\";\n    // Invariant missing -> OrleansConfigurationException\n});\n\n// after\nbuilder.UseAdoNetClustering(options =>\n{\n    options.ConnectionString = \"Server=...;Database=Orleans;...\";\n    options.Invariant = \"Microsoft.Data.SqlClient\";\n});","handlingStrategy":"validation","validationCode":"// Validate clustering client options at startup before the silo/client uses them\nvar inv = clusteringClientOptions.Invariant;\nif (string.IsNullOrWhiteSpace(inv))\n    throw new OrleansConfigurationException(\"AdoNet clustering Invariant is required\");\nif (!DbProviderFactories.GetFactoryInvariantNames().Contains(inv))\n    throw new OrleansConfigurationException($\"AdoNet provider invariant '{inv}' is not registered\");","typeGuard":"static bool HasValidInvariant(AdoNetClusteringClientOptions o) =>\n    !string.IsNullOrWhiteSpace(o.Invariant);","tryCatchPattern":"try { await client.Connect(); }\ncatch (OrleansConfigurationException cx) when (cx.Message.Contains(\"Invariant is required\"))\n{\n    _logger.LogCritical(\"Set AdoNetClusteringClientOptions.Invariant (e.g. 'Microsoft.Data.SqlClient')\");\n    throw;\n}","preventionTips":["Always set Invariant in the AdoNet clustering config section.","Reference the DB provider package and register its DbProviderFactory.","Validate the invariant string against registered providers at startup.","Keep a config template that includes the invariant field."],"tags":["adonet","clustering","config","validation","startup"],"backgroundTag":null,"analyzedSha":"fca799fa70ecb6ad975224271703ca43221f58de","analyzedAt":"2026-08-13T19:55:57.938Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}