What this usually means
The Options pattern relies on a contract between your POCO class and the configuration source. When binding fails silently, the usual culprit is a mismatch in naming — your class property name doesn't match the config key exactly (case-insensitive by default, but only if the configuration source preserves original casing). Environment variables on Linux collapse to uppercase, while JSON preserves case; docker secrets use file names as keys. Another common cause is missing the services.Configure<TOptions>() call, or calling it after the first resolution. Sometimes validation is run before binding completes (e.g., in the constructor of an IValidateOptions<T>). Less obvious: the configuration section might exist but be empty because of a colon vs. double-underscore separator mismatch in environment variables, or because a configuration builder (like AddJsonFile) points to a missing file and silently skips it.
The first ten minutes — establish facts before touching code.
- 11. Add `builder.Configuration.GetSection("YourSectionName").GetChildren().ToList().ForEach(c => Console.WriteLine($"{c.Key} = {c.Value}"));` right before `services.Configure<TOptions>`. Confirm keys match.
- 22. Check that your options class is a public class with public get/set properties. Private setters or internal class cause silent failures.
- 33. Verify you called `services.Configure<MyOptions>(builder.Configuration.GetSection("MySection"))`. Missing GetSection means binding from root.
- 44. For environment variables, run `printenv | grep -i YOURPREFIX` on Linux or `[Environment]::GetEnvironmentVariables()` in PowerShell. Confirm double underscores (__) as separators.
- 55. If using IOptionsSnapshot, ensure the service is registered as Scoped. If using IOptionsMonitor, check that you're not holding the reference forever.
- 66. Enable .NET configuration event source `DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2PROTOCOLS=0`? No — that's wrong. Actually, enable debug logging: set `Logging:LogLevel:Microsoft.Extensions.Configuration=Debug` in appsettings.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchProgram.cs / Startup.cs: the services.Configure<T>() call and its section name
- searchappsettings.json (or appsettings.{Environment}.json): the actual JSON structure, especially nesting and array syntax
- searchlaunchSettings.json: environment variables that might override file-based config
- searchYour options class (e.g., MyOptions.cs): property names, public getters/setters, default values
- searchdocker-compose.yml or K8s ConfigMap: environment variable names (double underscore separators, prefixes)
- searchGlobal configuration source list: builder.Configuration.Sources — check the order of precedence
- searchApplication Insights / Serilog: structured logs showing resolved configuration values
Practical causes, not theory. These are the things you will actually find.
- warningProperty name mismatch: JSON has 'database_name', C# property named 'DatabaseName' — default camelCase policy won't match
- warningMissing GetSection in Configure call: `services.Configure<MyOptions>(configuration)` binds from root, so only top-level properties work
- warningEnvironment variable separator: on Linux, `MySection__MyKey` — not `MySection:MyKey`. Windows supports both
- warningIOptionsSnapshot<T> used in Singleton: it captures config at creation time and never refreshes
- warningConfiguration file not reloaded: AddJsonFile without `reloadOnChange: true`, or file watcher fails due to permissions
- warningValidation executed before binding: custom ValidateOptions<T> that accesses nested config not yet bound
- warningStatic cache: IOptions<T> is resolved once and cached. If you mutate the options object, next resolution returns same mutated instance
Concrete fix directions. Pick the one that matches your root cause.
- buildExplicitly map properties with `[ConfigurationKeyName("database_name")]` to match non-standard JSON keys
- buildAlways use `GetSection("SectionName")` — never pass the root configuration to Configure<T> for a subsection
- buildSwitch to IOptionsMonitor<T> if you need hot-reload and are registering as Singleton; IOptionsSnapshot only works in Scoped/Transient
- buildFor environment variables, standardize on double underscore (`__`) separator. In Docker Compose, use `${MYVAR}` syntax and set them under environment:
- buildRun configuration validation early: call `options => options.Bind(config.GetSection("MySection"))` and check with `Debug.Assert` in startup
- buildUse `services.PostConfigure<T>(options => { /* override defaults */ })` to apply fallback values after binding
A fix you cannot prove is a guess. Close the loop.
- verifiedAfter fix, read config with `var opt = app.Services.GetRequiredService<IOptions<MyOptions>>().Value;` and log all properties
- verifiedSet an invalid value in config and confirm validation fires (if configured)
- verifiedChange a config value at runtime (e.g., edit appsettings.json while app runs) and verify IOptionsMonitor<T> picks it up within seconds
- verifiedCheck that the number of configuration children matches expected sections: `config.GetSection("MySection").GetChildren().Count()`
- verifiedFor arrays, confirm `config.GetSection("MyArraySection").GetChildren().Count()` returns the expected count
- verifiedUnit test: instantiate ConfigurationBuilder, add an in-memory collection, call Configure<T>, resolve options, assert properties
Things that make this bug worse or harder to find.
- warningDon't set properties as init-only or with private set — binding requires public setter
- warningDon't nest ConfigurationBuilder calls — you might create a separate config instance that doesn't merge
- warningDon't use IOptionsSnapshot in a Singleton — it's scoped by design and will throw or give stale data
- warningDon't forget that environment variables from Docker/K8s are uppercase by convention — your section names might need to match
- warningDon't assume validation runs before options are used — it runs on first access, not at registration time
- warningDon't mutate an options object returned by IOptions<T>.Value — it's shared across the app
Production incident: Database config silently defaulted to localhost
Timeline
- 09:15PagerDuty alert: 'High latency on /orders endpoint'. p95 response time spikes from 200ms to 7s.
- 09:18Check Application Insights: database dependency calls timing out. They target 'localhost:8081' instead of actual Cosmos endpoint.
- 09:20Review latest deployment: migrated from .NET Core 3.1 to .NET 6, changed config binding from custom ConfigManager to native IOptions<T>.
- 09:25Check appsettings.json in Kudu: correct Cosmos URI present under 'Database:EndpointUri'.
- 09:30Add debug log: `Console.WriteLine(config.GetSection("Database").GetChildren().Count());` — returns 0!
- 09:35Discover that in Program.cs, `services.Configure<DatabaseOptions>(configuration)` is called without GetSection. Options class has top-level properties like 'EndpointUri' but config root has 'Database' section wrapping them.
- 09:40Fix: change to `services.Configure<DatabaseOptions>(configuration.GetSection("Database"))`. Redeploy.
- 09:45p95 latency drops to 210ms. Incident resolved.
The alert came in as a spike in order API latency. Our p95 had gone from 200ms to 7 seconds. Quick glance at App Insights showed Cosmos DB calls were timing out. The target endpoint was 'localhost:8081' — the default from our DatabaseOptions class. But we had set the correct URI in appsettings.json under Database:EndpointUri. Something was not binding.
I checked the recent deployment: we had migrated from a custom ConfigManager to the native .NET IOptions pattern. The code looked innocent: `services.Configure<DatabaseOptions>(configuration)` in Program.cs. But the DatabaseOptions class had a property `EndpointUri`, and the config file had `"Database": { "EndpointUri": "https://mycosmos.documents.azure.com:443/" }`. The binding was trying to find `configuration["EndpointUri"]` at root level, not inside the "Database" section.
I added a debug line: `config.GetSection("Database").GetChildren().Count()` returned 0. That's when I realized the mistake: we passed the entire configuration root instead of the specific section. The fix was a one-liner: add `.GetSection("Database")`. After redeploy, within a minute the metrics normalized. The lesson: always use GetSection when your options class maps to a subsection of the config file.
Root cause
`services.Configure<DatabaseOptions>(configuration)` used the entire configuration root, but the options class expected properties at root level, while the actual values were nested under a 'Database' section. Binding silently failed, leaving default property values (null/localhost).
The fix
Changed to `services.Configure<DatabaseOptions>(configuration.GetSection("Database"))`.
The lesson
Never pass the root configuration object to Configure<T> if your JSON has a section wrapper. Always use GetSection. And add a startup validation that logs the bound values to catch silent failures early.
When you call `services.Configure<MyOptions>(config.GetSection("MySection"))`, the framework creates a named options instance (default name is Options.DefaultName, which is an empty string). It registers an IConfigureOptions<T> that, when the options object is first requested, calls config.Bind() on a new instance and returns it. The Bind() method iterates over the properties of T and tries to find matching keys in the configuration section (case-insensitive by default). If a property has a [ConfigurationKeyName] attribute, that name is used; otherwise the property name is used as-is.
A common misunderstanding is that binding uses camelCase. It does not. The default behavior is case-insensitive, but only if the underlying configuration source preserves the original casing. JSON files preserve casing, so a JSON key 'EndpointUri' matches property 'EndpointUri'. Environment variables on Linux are uppercase by default, so 'ENDPOINTURI' matches 'EndpointUri' (case-insensitive). But if your property is 'EndpointURI' and your env var is 'EndpointUri', it will fail because the match is case-insensitive but the env var name is exactly 'EndpointUri'. The fix is to either standardize naming or use attributes.
The most reliable way to debug binding issues is to examine the IConfiguration object directly. Insert a breakpoint or log statement after your ConfigurationBuilder is built: `foreach (var kvp in config.AsEnumerable()) Console.WriteLine($"{kvp.Key} = {kvp.Value}");`. This flattens the entire config tree into key-value pairs using the colon delimiter. You'll immediately see if your section exists and with what keys.
If you're using environment variables, remember that on Linux, the colon ':' is not a valid environment variable separator — you must use double underscore '__'. The framework normalizes '__' to ':' internally, but only if you use the EnvironmentVariables configuration provider with the default prefix. If you specify a prefix (e.g., `AddEnvironmentVariables("MYAPP_")`), the prefix is stripped and the rest must use '__' as separator. A common mistake is using single underscore or dot separator, which won't be parsed as hierarchy.
IOptionsSnapshot<T> is designed for scenarios where you want configuration to be re-read per request. It implements IDisposable and is registered as Scoped. If you inject IOptionsSnapshot<T> into a Singleton service, it will be resolved once and never update. Worse, the framework may throw an ObjectDisposedException if the scoped lifetime ends. Always use IOptionsMonitor<T> if you need configuration changes in a Singleton.
Another subtlety: reloadOnChange: true on AddJsonFile relies on a file system watcher. On some hosting environments (like Azure App Service on Windows), the file watcher may not detect changes reliably because the file is copied to a different location. In such cases, consider using a polling approach or restarting the app on config changes.
If you implement IValidateOptions<T> or use ValidateDataAnnotations, validation runs when the options object is first resolved, not during registration. This means if your validation logic depends on a different section of configuration that hasn't been bound yet, you might get false positives. A workaround is to use PostConfigure to set defaults before validation, or validate after all configuration is loaded.
I've seen cases where a custom ValidateOptions<T> in the constructor accesses `config.GetSection("OtherSection")` but that section hasn't been added to the builder yet because the order of service registration matters. The fix is to ensure all configuration sources are added before any services that depend on them, or to use IOptionsMonitor's OnChange event to trigger validation asynchronously.
Frequently asked questions
Why does my IOptions<T> return default values even though appsettings.json has the correct data?
Most likely you passed the entire configuration object to Configure<T> instead of using GetSection. For example, if your JSON has "Database": { "Port": 5432 } and your class has a Port property, you must call `services.Configure<DbOptions>(config.GetSection("Database"))`. If you just pass config, it looks for a top-level "Port" key, which doesn't exist, so it stays at default.
How do I bind environment variables to a nested options class?
Use double underscore `__` as separator. For a section "Database" with property "ConnectionString", set the environment variable `Database__ConnectionString=value`. On Windows, you can also use colon `:`, but for cross-platform compatibility, always use double underscore. Also ensure you've called `builder.Configuration.AddEnvironmentVariables()` and that the prefix (if any) matches.
IOptionsSnapshot doesn't refresh when I change appsettings.json. What's wrong?
First, verify that you added the JSON file with `reloadOnChange: true` (the default is false). Second, ensure the service that injects IOptionsSnapshot is scoped or transient — not singleton. If it's singleton, the snapshot is captured once. Finally, check file permissions: the app process must have read access to the file, and the file watcher must be supported (not in some locked-down environments like Azure Functions on Consumption plan).
Can I bind to properties with private setters?
No. The configuration binder requires public getters and setters. If you want immutable options, you can use the IOptions pattern with a record (C# 9+) but still need public init-only setters, which the binder can set only if you call Bind() with options => options.Bind()? Actually, Bind() does support init-only setters as of .NET 6. But the safest approach is to use public get/set.