Azure Functions Event Hubs: Fix Sovereign Checkpoints

An Azure Functions Event Hubs trigger can authenticate successfully to Event Hubs and still stop before processing events because its checkpoint client is trying the wrong Azure Storage endpoint. That failure was possible when AzureWebJobsStorage__accountName and an explicit AzureWebJobsStorage__blobServiceUri were both present: Event Hubs extension versions before 6.5.4 could construct a public-cloud blob.core.windows.net URI instead of honoring the sovereign-cloud blob URI.

Version 6.5.4 of Microsoft.Azure.WebJobs.Extensions.EventHubs, released on September 9, 2026, changes that precedence. The checkpoint store now prefers AzureWebJobsStorage__blobServiceUri; it can also honor AzureWebJobsStorage__endpointSuffix when it must construct a URI from an account name. This guide keeps the safer, documented service-URI configuration as the primary path, shows how to roll out the fixed package in a .NET Functions app, and defines evidence that the checkpoint path is actually healthy.

Recognize the Endpoint-Precedence Failure

The useful symptom is not simply “the trigger is idle.” Look for a storage request or DNS error that names a public Azure endpoint even though the function app runs in another cloud. A representative failing host attempts a URI shaped like this:

https://<storage-account>.blob.core.windows.net

For an app in Azure Government or Azure China, that hostname is a strong diagnostic signal. Microsoft documents AzureWebJobsStorage as host storage used for normal Functions operations, including Event Hubs checkpoints. A healthy Event Hubs listener therefore needs two independent connection paths to work: its connection to Event Hubs and its access to the blob checkpoint store.

Confirm the mismatch without exposing secrets:

Record the cloud in which the function app and storage account are deployed.

Read the storage account’s blob data-plane endpoint from the resource, rather than composing it from memory.
Inspect the function app settings for AzureWebJobsStorage__accountName and AzureWebJobsStorage__blobServiceUri.
Search host logs for the hostname contacted by the checkpoint client.

Use Azure CLI to retrieve the authoritative endpoints:

az storage account show \
  --resource-group "$RESOURCE_GROUP" \
  --name "$STORAGE_ACCOUNT" \
  --query primaryEndpoints \
  --output json

Do not paste production setting values or access tokens into an incident ticket. The endpoint hostname, package version, cloud name, timestamp, and exception type are enough to prove this particular mismatch.

Upgrade the Event Hubs Extension Deliberately

For a .NET Functions project that references the binding extension directly, pin version 6.5.4 or later in the project file:

<ItemGroup>
  <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.EventHubs"
                    Version="6.5.4" />
</ItemGroup>

Restore in locked mode if the repository uses a NuGet lock file, then verify the resolved dependency rather than trusting the project edit:

dotnet restore --locked-mode
dotnet list package --include-transitive \
  | grep Microsoft.Azure.WebJobs.Extensions.EventHubs

The output must resolve the Event Hubs extension to 6.5.4 or a later version that retains the fix. Capture that output in the deployment evidence.

This instruction does not automatically apply to every Functions language model. Non-.NET apps commonly receive binding extensions through an extension bundle. A bundle version range does not prove which Event Hubs extension reached the running host. For a bundle-based app, inspect the resolved bundle contents or host startup inventory and wait for a bundle containing the fix. Do not add a .NET package reference to a Python, JavaScript, or PowerShell app merely to force the version.

The package update also adds other changes, including a net10.0 target, but those changes are not the reason for this rollout. Keep the change request scoped to checkpoint endpoint selection so that rollback and validation remain clear.

Prefer Explicit Service URIs in Sovereign Clouds

Microsoft’s Functions app-settings reference says sovereign-cloud and custom-DNS deployments should use the service-specific URI settings instead of relying on AzureWebJobsStorage__accountName. Preserve that intent even though 6.5.4 can honor an endpoint suffix.

Set the endpoints using values returned by the storage account:

az functionapp config appsettings set \
  --resource-group "$RESOURCE_GROUP" \
  --name "$FUNCTION_APP" \
  --settings \
    "AzureWebJobsStorage__blobServiceUri=$BLOB_SERVICE_URI" \
    "AzureWebJobsStorage__queueServiceUri=$QUEUE_SERVICE_URI" \
    "AzureWebJobsStorage__tableServiceUri=$TABLE_SERVICE_URI" \
    "AzureWebJobsStorage__credential=managedidentity"

For a system-assigned identity, no client ID is necessary. For a user-assigned identity, also set one supported identity selector:

AzureWebJobsStorage__credential=managedidentity
AzureWebJobsStorage__clientId=<user-assigned-identity-client-id>

Do not set both AzureWebJobsStorage__clientId and AzureWebJobsStorage__managedIdentityResourceId. Microsoft documents them as alternatives. Also remember that changing app settings restarts the function app; use a deployment slot or a rolling update strategy when the hosting plan and availability requirements justify it.

If infrastructure automation continues to inject AzureWebJobsStorage__accountName, 6.5.4 makes that coexistence safe for the checkpoint client because the explicit blob URI wins. Still keep the full service URIs in the desired state. Removing them and relying on the new __endpointSuffix option expands the change unnecessarily and departs from the current Functions guidance.

Validate Identity and Network Access Separately

The package fix corrects endpoint selection. It does not grant permissions, create private DNS records, or open a network path. Treat those as separate gates.

First, confirm the intended managed identity is enabled on the function app. Then compare its role assignments with the current Functions identity-based host-storage requirements and the least privilege allowed by your design. The checkpoint operation needs blob data-plane access; other host operations can also need queue and table access. A successful token acquisition does not prove that the identity can read and write checkpoint blobs.

Next, validate name resolution and transport from the app’s network path. In a private-endpoint deployment, the correct sovereign hostname can still resolve to the wrong address or be blocked by routing, firewall, or private DNS configuration. Distinguish these cases in logs:

A public-cloud hostname indicates endpoint selection or stale configuration.
The correct hostname with 403 indicates authentication or authorization.
The correct hostname with a DNS or connection timeout indicates network or private-DNS work.
Successful storage calls followed by listener errors move the investigation back to the Event Hubs connection, consumer group, or function code.

This split prevents a package upgrade from being credited for an unrelated RBAC or network repair.

Prove the Listener and Checkpoint Path After Deployment

Validate in a non-production slot or representative environment first. App startup alone is insufficient because the listener may initialize before any checkpoint write becomes observable.

Run this bounded verification:

Deploy the artifact containing Event Hubs extension 6.5.4.
Confirm the running artifact or startup inventory reports the intended package or resolved bundle.

Confirm logs contain no checkpoint request to blob.core.windows.net when that is not the storage account’s cloud endpoint.
Send a uniquely identified test event to the configured event hub.
Confirm the target function processes that event once for the tested consumer group.

Confirm a checkpoint blob in the configured storage account advances after processing.

Use the actual checkpoint container from your environment rather than assuming a container name:

az storage blob list \
  --account-name "$STORAGE_ACCOUNT" \
  --container-name "$CHECKPOINT_CONTAINER" \
  --auth-mode login \
  --query "[].{name:name,lastModified:properties.lastModified}" \
  --output table

Capture the blob path and lastModified value before and after the test event. The operator running this command also needs suitable data-plane permission; a local CLI authorization failure does not prove that the function’s managed identity failed.

The minimum acceptance evidence is therefore a chain: resolved fixed extension, correct blob hostname, processed test event, and advancing checkpoint. Any single item by itself leaves a gap. A log line with the right endpoint does not show write permission, while a processed event without checkpoint evidence can hide replay risk after a restart.

Restart the slot once after the first successful checkpoint and send a second unique event. The listener should resume from its stored position rather than replaying the entire partition. Do not use production traffic volume or duplicate counts as a casual experiment; keep the test consumer group and event identifiers controlled.

Roll Out Without Creating a Checkpoint Incident

Deploy one slot or one low-risk app first. If multiple apps share a consumer group, avoid overlapping listeners during a slot swap because ownership rebalancing can make the verification noisy. Record the app version, extension version, consumer group, storage account, blob endpoint, and test-event ID in the change record.

Keep these production edges in view:

Stale instances: app-setting changes restart the app, but verify every instance is running the new artifact before closing the incident.
Mixed extension delivery: direct NuGet references and extension bundles have different upgrade paths; do not infer one from the other.
Private endpoints: explicit service URIs still require correct DNS resolution inside the integrated network.

User-assigned identities: a correct client ID with missing storage roles produces a different failure from the old endpoint bug.
Consumer-group reuse: two environments sharing a consumer group and checkpoint container can disturb each other’s positions.
Slot settings: mark environment-specific storage settings as deployment-slot settings where appropriate, or a swap can point production at the wrong checkpoint store.

Rollback should reverse the application artifact, not erase checkpoint data. Deleting checkpoints can replay events and turn a package rollback into a data-processing incident. If the older extension cannot work with the required sovereign endpoint, rollback to the last known-good artifact and configuration pair, pause the trigger if necessary, and preserve the failed deployment evidence for diagnosis.

Use Azure Functions Event Hubs 6.5.4 as the Long-Term Contract

The durable configuration contract is straightforward: deploy Event Hubs extension 6.5.4 or later, provide explicit storage service URIs for sovereign clouds or custom DNS, and let the managed identity authenticate to those exact endpoints. The extension’s new precedence removes the conflict when automation also supplies AzureWebJobsStorage__accountName; it does not replace endpoint discovery, RBAC, network validation, or checkpoint readback.

Treat the public-cloud hostname as a regression signal. A lightweight post-deployment query can alert when a sovereign-cloud function contacts blob.core.windows.net, while the release gate verifies one controlled event and an advancing checkpoint. Together those checks catch both the original endpoint-selection bug and the operational failures that can look similar.