App Config Emulator: Label=%00 Fails For Null Keys?

Dec 3, 2025 by Alex Johnson 52 views

App Configuration Emulator: Label=%00 Fails for Null-Labeled Keys

This article addresses a critical issue encountered while using the Azure App Configuration Emulator: the failure of the label=%00 filter when querying for keys with null labels. This behavior, confirmed across multiple API versions (2023-11-01, 2024-09-01) and emulator version 1.0, deviates from the expected functionality and impacts applications relying on this filtering mechanism.

Understanding the Issue

The core problem lies in how the App Configuration Emulator handles requests filtering by null labels. According to the Azure App Configuration REST API documentation, using %00 as a label filter should match key-value pairs where the label is explicitly set to null. This is a crucial feature for scenarios where you need to distinguish between keys with specific labels and those without any label (null label). However, the emulator incorrectly returns a 404 Not Found error when label=%00 is used, even though keys with null labels are present.

This discrepancy creates a significant challenge for developers using the emulator for local testing and development. Applications relying on the %00 filter to identify and retrieve keys with null labels will not function as expected in the emulator environment. This can lead to unexpected behavior and hinder the development process. Understanding the root cause and potential workarounds is crucial for mitigating this issue.

Reproducing the Issue: Step-by-Step Guide

To illustrate the problem, let's walk through a step-by-step reproduction using PowerShell and the App Configuration Emulator. This example will use a simple key-value pair with a null label to demonstrate the failure of the label=%00 filter.

1. Setting up the Emulator

First, ensure you have the App Configuration Emulator running. In this example, we're using the mcr.microsoft.com/azure-app-configuration/app-configuration-emulator:1.0.0 image. If you're using .NET Aspire, it can automatically manage the emulator container for you. Once the emulator is running, note the endpoint URL (e.g., http://localhost:65083).

2. Seeding the Emulator with Data

Next, we'll seed the emulator with a key-value pair that has a null label. This is the crucial step in demonstrating the issue. The following JSON represents the data we'll add to the emulator:

{"key":"shared:config:sentinel","label":null,"value":"1758876683","content_type":""}

This JSON defines a key named shared:config:sentinel with a null label and a corresponding value. To add this data to the emulator, you would typically use a tool or script that interacts with the emulator's API. For example, you might use a POST request to the /kv endpoint.

3. Verifying the Entry and its Null Label

To confirm that the entry was added correctly and that the label is indeed null, we can use a GET request with a wildcard (*) for the label. This will retrieve all key-value pairs matching the key, regardless of their label. Execute the following PowerShell command:

Invoke-RestMethod "http://localhost:65083/kv?key=shared:config:sentinel&label=*" | ConvertTo-Json -Depth 5

The response should include the key-value pair we added, and the label property should have a value of null, as shown in the example provided in the original issue description.

4. Requesting the Key Without a Label Filter

Before attempting to filter by the null label, let's verify that we can retrieve the key without any label filtering. This ensures that the key itself is accessible and that the issue is specifically related to the label filtering. Execute the following command:

Invoke-RestMethod "http://localhost:65083/kv/shared:config:sentinel?api-version=2023-11-01"

This request should successfully return the key-value pair.

5. Adding the Label Filter for “No Label” using %00

Now, let's introduce the problematic filter. We'll use label=%00 to specifically target key-value pairs with null labels. Execute the following command:

Invoke-RestMethod "http://localhost:65083/kv/shared:config:sentinel?label=%00&api-version=2023-11-01"

6. Observing the Unexpected Response

This is where the issue manifests. Instead of returning the key-value pair with the null label, the emulator will respond with a 404 Not Found error. This confirms the bug: the label=%00 filter is not working as expected in the App Configuration Emulator.

Expected vs. Actual Behavior

Expected: Filtering with label=%00 should match entries whose label is null. This is the behavior in the cloud service.
Actual: The emulator returns a 404 Not Found error when label=%00 is present, even though the entry's label is null and the same key is returned when the label filter is omitted.

Impact on Applications

This bug has a direct impact on applications that rely on the App Configuration SDK and use the %00 label filter. The SDK often uses this filter internally for sentinel probes and other operations related to managing configuration settings with no specific label. When running against the emulator, these applications may experience unexpected behavior, such as failing to retrieve configuration values or encountering errors during initialization. This discrepancy between the emulator and the cloud service makes it challenging to develop and test applications locally.

The .NET App Configuration SDK (specifically version 8.4.0 in this case) is one example of a library that relies on this behavior. When used with .NET Aspire (Aspire.Hosting.Azure.AppConfiguration 9.5.1), which automatically runs the emulator container, the issue becomes readily apparent. Aspire utilizes the App Configuration Emulator for local development and testing, making it a common scenario where this bug can surface.

Potential Workarounds and Solutions

While the ideal solution is for the App Configuration Emulator to be updated to correctly handle the label=%00 filter, there are some potential workarounds that developers can use in the meantime.

1. Avoid Using Null Labels (If Possible)

If your application's design allows, the simplest workaround is to avoid using null labels altogether. Instead, consider using an explicit label (e.g., a label with an empty string or a specific reserved label) to represent the absence of a label. This will allow you to filter using standard label filters without relying on the problematic %00 syntax. However, this might require significant changes to your configuration structure and application code.

2. Modify the Query Logic (If Feasible)

Another approach is to modify your application's query logic to account for the emulator's behavior. This might involve adding conditional logic that uses a different filtering strategy when running against the emulator. For example, you could omit the label filter entirely when running locally or use a different API call to retrieve all keys and then filter them in code. This workaround can be complex and may introduce inconsistencies between the emulator and cloud service behavior.

3. Use a Specific Label Value Instead of Null

Instead of setting the label to null, use a specific value, such as "no label" or an empty string. Then, filter for that specific value instead of using %00. This approach requires modifying your configuration data but can provide a more consistent experience across different environments.

4. Wait for an Emulator Update

The most straightforward solution is to wait for an official update to the App Configuration Emulator that addresses this bug. Microsoft is aware of the issue and is likely working on a fix. Keep an eye on the emulator's release notes and changelog for updates. In the meantime, you can use the workarounds mentioned above to mitigate the problem.

Conclusion

The failure of the label=%00 filter in the App Configuration Emulator for null-labeled keys is a significant issue that can impact applications relying on this filtering mechanism. This article has detailed the problem, provided a step-by-step guide to reproduce it, discussed its impact, and offered potential workarounds. While these workarounds can help mitigate the issue, the best long-term solution is an official update to the emulator. Developers should monitor the emulator's release notes for updates and consider the workarounds discussed in this article to ensure their applications function correctly in both local and cloud environments.

For further information about Azure App Configuration and its features, please visit the official Azure App Configuration documentation.