Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This article helps you diagnose and resolve problems with Microsoft Discovery when you don't have a specific error code to look up. It covers deployment, supercomputers, workspaces, networking, bookshelves and knowledge bases, and tools and agents.
Start with the general troubleshooting checklist. Then go to the section that matches your symptom for likely causes and solutions. If you already have a specific error code or message, see Microsoft Discovery error codes. Before you open a support request, also review Known issues for Microsoft Discovery.
Prerequisites
- An Azure account with an active subscription. Create an account for free.
- A Microsoft Discovery environment that's deployed or being deployed.
- The required Discovery role assignments. See Role assignments for Microsoft Discovery.
- Access to the Activity Log and to Log Analytics to query platform logs. See Query supercomputer logs and Query workspace logs.
Troubleshooting checklist
Work through these steps first. They identify the cause of most problems and provide the evidence you need for the sections that follow.
Capture the correlation ID and read the operation history
For an Azure Resource Manager operation, capture the correlation ID and inspect the deployment operation history and Activity Log for the failing operation. See Get operation correlation ID from Activity Log.
For a workspace data-plane request or tool run, capture the response, timestamp, and available request, conversation, or run identifiers, then query the relevant application logs. An ARM correlation ID doesn't necessarily identify the application request, and the Activity Log isn't a record of all data-plane activity. See Access resource logs.
Check the resource provisioning state
Confirm the resource's provisioningState. Succeeded means the operation completed, Accepted usually means the operation is still in progress, and Failed means you must inspect the operation history before you retry. Some resource types must be deleted and recreated after they enter a terminal Failed state.
Verify the deploying identity's roles
Confirm the required roles are assigned to the identity that runs the operation. For a pipeline, check the service principal or managed identity rather than the interactive user. Azure ownership permissions don't replace the Discovery data-plane and supporting service roles described in Role assignments in Microsoft Discovery.
Confirm the region and API version
Confirm the target region is supported and the request uses the API version that ships with the current Toolbox or infrastructure quickstart.
Query the relevant logs
Query supercomputer, workspace, and bookshelf logs to locate the failing phase. See Query supercomputer logs, Query workspace logs, and Query bookshelf logs.
Potential quick workarounds
These workarounds can restore service quickly. For a permanent fix, use the cause and solution sections that follow.
Retry a transient failure
- If an operation returns an
InternalServerErroror a timeout, check its outcome and resource state before retrying. The response alone doesn't establish a transient failure. - Retry only when the operation supports safe retries and the evidence indicates a temporary failure. Use bounded backoff and honor
Retry-Afterwhen returned. Don't delete partially created resources unless the resource-specific guidance requires recreation. - If the failure persists or the cause isn't clear, create an Azure support request with the response, timestamp, and relevant identifiers.
Pin a job to a known-good node pool
- In the project preference, set the correct node pool explicitly (
nodePoolId). - Resubmit the job or tool run.
Deployment fails because the identity is missing required roles
Deployment reaches an operation that needs a data-plane, network-perimeter, storage, or Foundry permission that the deploying identity doesn't have.
Solution: Assign the full role set to the deploying identity
- Assign the platform administrator persona roles to the identity that runs the deployment. Include the network security perimeter, storage data-plane, and Foundry roles required for the resources in your deployment.
- Preview the assignments with the
Set-DiscoveryRoleAssignments.ps1script and its-WhatIfparameter, and then run the script without-WhatIf. See Assign persona roles with a PowerShell script. - Wait several minutes for role and network-perimeter propagation.
- Rerun the deployment. See Role assignments for Microsoft Discovery.
Deployment fails or is blocked in a specific region
A region can be restricted or withdrawn for Discovery managed resources even when it appears selectable. Resource-group location policies can also block where you create virtual networks or resource groups. Capacity or quota might also contribute to deployment failure.
Solution: Deploy to a supported region and add policy exemptions
- Deploy to a supported region.
- If a required role is eligible through Privileged Identity Management (PIM), activate it before deploying.
- Create the resource group in the correct region. If an organizational policy blocks the deployment, ask the policy administrator whether an exemption is permitted at the required scope.
- Check model and compute quota in the target region. Request additional quota if needed. If capacity isn't available, select another supported target region.
For a region that appears selectable but isn't supported, see Known issues for Microsoft Discovery.
Cross-region managed resources deploy to the wrong region
For a cross-region deployment, verify that the discovery.overridemrgregion tag was present on each supported Discovery resource when it was created. The value must be a valid Azure programmatic region identifier, and the target region must support Discovery cross-region deployment and the required Foundry features.
If resources can't communicate, check network security groups, routes, firewalls, private endpoints, and private DNS. Verify that managed identities can access storage accounts, the container registry, and other dependencies.
Deployment appears stuck and never finishes
The deployment fails internally but keeps retrying components, so it looks like it's still running.
Solution: Find and fix the first internal failure
- Open the deployment operation history and find the first operation that failed.
- Resolve that root cause, which is commonly a missing role, a network feature, or a subnet or quota limit.
- Rerun the deployment.
A Discovery resource is stuck in a terminal failed state
Some Discovery resources can't be updated after they enter a terminal Failed state, so further operations return a conflict.
Solution: Delete and recreate the failed resource
- Confirm from the operation history that the resource is in a terminal
Failedstate and can't be retried. - Delete only the failed resource. For a workspace, leave the resource group, storage, and supercomputer in place.
- Recreate the resource with a new name and the correct prerequisites.
- To free a supercomputer that's bound to a stuck workspace, remove the supercomputer association from within the workspace instead of deleting the supercomputer. See Manage Microsoft Discovery workspaces and Delete Microsoft Discovery resources.
Supercomputer creation fails with a webhook timeout
During the internal Helm install of the supercomputer, the kueue-webhook-service in the kueue-system namespace returns a 504 Gateway Timeout to the network-operator pre-upgrade hook, and the install fails. This condition is transient.
Solution: Retry creation and confirm the latest release
- Retry supercomputer creation.
- Confirm you're on the latest platform release.
- If it persists, inspect the pod behind
kueue-webhook-servicein thekueue-systemnamespace. See Query supercomputer logs.
The managed cluster fails during node-pool provisioning
The Activity Log shows failures during managed cluster provisioning because the supercomputer subnet is too small for node-pool scaling.
Solution: Increase the subnet size and redeploy
- Increase the AKS and supercomputer subnet to at least
/24. - Redeploy the supercomputer.
- Validate that node-pool creation succeeds.
Supercomputer jobs terminate unexpectedly
Check the job and node events before assigning a cause. Discovery uses a Pod Disruption Budget (PDB) that can block voluntary eviction of an active tool during an AKS node-pool upgrade. A PDB doesn't prevent involuntary disruptions such as hardware failure, node loss, or resource exhaustion. See Supercomputer AKS upgrades.
Solution: Inspect the run and verify the node pool
- Review the affected run and job and node events in the supercomputer logs.
- Verify the
nodePoolIdin the project preference identifies the intended pool. Selecting a pool doesn't repair unhealthy nodes or guarantee scheduling capacity. - If a node or GPU node pool is unhealthy, collect its state and events and contact your administrator or Microsoft Support for a supported recovery procedure. Don't modify the backing AKS resources directly. See Debug task execution.
Supercomputer nodes never reach the Ready state
Nodes provision at the infrastructure layer but never join the cluster, and the supercomputer stays in a provisioning or failed state. Bootstrap failures happen before your containers run, so application logs might contain no useful evidence.
Solution: Check bootstrap dependencies and cluster health
- Check that nodes can resolve
mcr.microsoft.comandmanagement.azure.com, and that DNS responses return along the same path as the query. - Compare outbound rules with the supercomputer network requirements and AKS outbound rules. Check container image and OS package endpoints, including dependencies covered by Azure Front Door service tags.
- For
UserDefinedRouting, verify node subnets can reach the management subnet on ports 443 and 4443. Check rules on the management subnet's network security group, not only the node subnets. - Inspect virtual network flow logs during the provisioning window. A denied flow identifies the matching rule. If there are no deny records, check effective routes and the egress appliance for drops, asymmetric paths, and source network address translation port exhaustion.
- Verify subnet delegations against the onboarding validation checks. For
UserDefinedRouting, the management subnet requiresMicrosoft.ContainerService/managedClustersdelegation; the system-node and node-pool subnets must remain undelegated. - Check subnet IP availability, VM quota and SKU availability, Azure Policy denials, managed identity permissions, and role assignment failures.
- Inspect the virtual machine scale set instance and extension provisioning state for the specific failure.
Flow logs have three limitations:
- Traffic dropped by routing, an egress appliance, or a DNS failure doesn't reach network security group evaluation. No deny record isn't proof that traffic was allowed.
- A capture only covers the lifecycle events observed. Bootstrap, upgrade, and failover rules might have no matches in a steady-state capture. Don't remove a rule solely because it matched nothing.
- Flow logs are aggregated, not real time. Allow several collection intervals before concluding a flow didn't occur.
Configuration checks don't prove packet-level connectivity or available compute capacity. Correlate them with the provisioning error and observed network traffic. After correcting a confirmed customer-managed configuration problem, use a supported Discovery recovery procedure with your administrator or Microsoft Support. Don't reconcile the backing AKS cluster, reimage instances, or change resources in the managed resource group directly.
A node pool fails to delete
If node pool deletion returns InternalServerError with the target internalMetadata, inspect the deletion operation and the backing AKS cluster state. A Failed or Deallocated cluster is useful diagnostic evidence, but the error alone doesn't establish the cause or a customer-run repair.
Solution: Collect cluster state and use supported recovery
Check the cluster in the supercomputer's managed resource group. This command is read-only; replace the placeholders with the actual resource names.
az aks show --resource-group "{managedResourceGroup}" --name "{aksClusterName}" \ --query "{provisioningState:provisioningState, powerState:powerState.code}"Collect the failed deletion response, timestamp, ARM correlation ID, and cluster state for Microsoft Support. Don't run
az aks updateor modify the backing resources in the managed resource group as a repair.Retry deletion through Discovery only after the supported recovery procedure indicates it's safe. See Delete Microsoft Discovery resources.
Tool runs fail because resources aren't allowlisted
A storage account or supercomputer exists but isn't associated with the workspace, so tool runs that reference it are rejected with a "Resources not allowed" error.
Solution: Allowlist the storage account and supercomputer in the workspace
- Associate (allowlist) the storage account and the supercomputer in the workspace.
- Rerun the tool. See Manage Microsoft Discovery workspaces.
Workspace creation fails because of insufficient quota
The workspace's Azure Container Apps environment requires enough quota to create. For the Enterprise SKU, the environment needs at least 80 cores.
Solution: Increase the container environment quota
- Request or confirm at least 80 cores of Azure Container Apps quota in the target region.
- Retry workspace creation. See Quota and reservations.
Workspace creation fails validation
Check the first failed operation for the following conditions:
- Name conflict: Workspace names must be globally unique and lowercase. Choose a different name if the failure identifies a naming conflict.
- Permissions: Verify the deploying identity has Microsoft Discovery Platform Administrator (Preview) or Owner on the resource group, plus the required supporting roles.
- Subnet delegation: Verify
workspaceSubnetandagentSubnetare delegated toMicrosoft.App/environments. - Quota: Use the workspace quota checks.
- Identity: Use the workspace identity checks.
The workspace host doesn't resolve over a private endpoint
Private DNS isn't resolving the workspace data-plane host from inside the virtual network after you enable network isolation or disable public access, so investigations are unreachable over Private Link.
Solution: Fix private DNS resolution
Read the private endpoint's DNS configuration and verify the required zone and A-records for the actual workspace data-plane host.
Confirm the private endpoint is approved and linked to the correct virtual network and subnet.
Confirm the private DNS zone is linked to the client virtual network and the private endpoint has the correct DNS zone group. With custom DNS, check forwarding to Azure DNS (
168.63.129.16) through the appropriate Azure-connected DNS path. See Configure private DNS.Validate resolution from a host inside the virtual network:
nslookup "{workspaceDataPlaneHostname}"Replace
{workspaceDataPlaneHostname}with the host from the workspace data-plane endpoint. Confirm the result matches the private endpoint's IP address. Successful DNS resolution alone doesn't prove API connectivity.Apply the same checks to a bring-your-own Cosmos DB private endpoint when project creation depends on it. See Network security for Microsoft Discovery.
If public network access is disabled, connect to the workspace from a private network path through a private endpoint, VPN, or ExpressRoute. Discovery Studio users also need that path. Don't enable public access as a routine troubleshooting fix.
Network hardening or private endpoint access fails
Missing permission to perform joinPerimeterRule/action
The custom NSP Perimeter Joiner role assignment is missing or hasn't propagated.
- Verify the role assignment.
- Confirm the assignment is at subscription scope, not resource group scope.
- Wait up to five minutes for Azure RBAC propagation.
- Retry workspace creation. The create-or-update operation is idempotent.
Service principal not found
If the Discovery Control Plane service principal doesn't exist in your tenant, create it, then retry the role assignment:
az ad sp create --id 92c174ac-8e41-4815-a1b7-d81b19ab03ce
An approved private endpoint still returns API errors
| Error | Checks and resolution |
|---|---|
| 504 Gateway Timeout | The backend might be temporarily unavailable. Compare with the public path only if that path is already allowed by your network policy. Don't enable public access for this test. If both allowed paths fail, check service availability. |
| 401 Unauthorized | Verify the token audience is https://discovery.azure.com/ and the caller has the required role on the resource. |
| DNS resolves to a public IP | Follow the private DNS checks. |
Network security group rules block deployment and usage
DenyAllInbound and DenyAllOutbound rules applied to every subnet block the traffic Discovery needs, so deployment fails and, even after deployment, chat or agent operations fail.
Solution: Scope network security group rules to the correct subnets
- Attach the required allow rules to the correct network security group for the supercomputer subnets. See Plan network security groups for a Microsoft Discovery supercomputer.
- Remove blanket deny rules that apply to every subnet.
- If agent operations still appear blocked by rules, create an Azure support request with the affected subnet and network security group details.
Supercomputer deployment stalls because a required public IP feature isn't registered
For a network configuration that uses a public IP address, the supercomputer deployment can get stuck when the bring-your-own public IP network feature isn't registered on the subscription. This condition causes an internal failure that the deployment keeps retrying. If Azure Policy blocks public IP creation, see Known issues for Microsoft Discovery instead.
Solution: Register the network feature and redeploy
Run the following commands to register the feature and re-register the provider:
az feature register --namespace Microsoft.Network --name AllowBringYourOwnPublicIpAddress az provider register -n Microsoft.NetworkRun the following command to confirm that the feature state is
Registered, and then redeploy:az feature show --namespace Microsoft.Network --name AllowBringYourOwnPublicIpAddress -o table
Knowledge base creation fails validation
A 400 response from the classic knowledge-base version endpoint can identify an invalid version or name. A browser chunked-encoding error alone doesn't identify the validation failure; inspect the response and operation logs. Also confirm that the bookshelf's provisioningState is Succeeded.
Solution: Use a valid name and version, and wait for provisioning
- For the classic knowledge-base version endpoint with API version
2026-02-01-preview, use aversionNameof 1-24 ASCII letters, digits, or hyphens. For example,1is valid, but1.0isn't. These constraints don't define the contract for other API versions. - Check the bookshelf and knowledge base names against the constraints for the API or Studio experience you're using.
- Wait for
provisioningStateto reachSucceededbefore you continue. See Index a bookshelf knowledge base.
Bookshelf indexing fails or silently drops documents
Indexing can fail on a very large single document or from a transient database timeout. In some cases, a large document is dropped from the index even though indexing reports success.
Solution: Check indexing logs and split large documents
- Check the bookshelf indexing logs for the affected document. See Query bookshelf indexing logs.
- Split very large PDFs, and confirm document sizes against the current ingest limits.
- Confirm sufficient embedding and retrieval model quota in the region.
- Ensure you're on a platform release with ingest improvements, and then retry.
Project or agent creation fails with a 500 error
A 500 response during project or agent creation doesn't identify a cause by itself. Check the project identity's Foundry permissions and, if you use bring-your-own Cosmos DB, its private endpoint and DNS configuration. Use the response and logs to determine whether either check relates to the failure.
Solution: Verify Foundry roles and Cosmos DB connectivity
- Verify the Foundry User role is assigned to the project managed identity.
- Validate the bring-your-own Cosmos DB private endpoint connectivity and DNS.
- If the error persists or a failed project can't be deleted through Discovery, contact Microsoft Support with the response, timestamp, and available request identifiers. Don't modify backing managed resources as a cleanup action. See Agent creation.
Tool execution fails with an invalid message id
An invalid or mismatched message identifier passed from the agent to the tool prevents tool invocation, so prompts that use tools can't complete.
Solution: Update to a fixed release and collect definitions
- Ensure you're on a release that includes the message ID fix and diagnostic logging.
- Apply any recommended prompt-level improvements.
- Collect the agent, workflow, and tool definitions to reproduce the issue. See Debug task execution.
Managed identity operations fail
Storage access denied
Storage container creation or blob operations fail with 403 Forbidden, AuthorizationFailed, AuthorizationPermissionMismatch, or This request is not authorized to perform this operation.
Verify that the workspace's user-assigned managed identity (UAMI) has Storage Blob Data Contributor on the target storage account. For example:
az role assignment create \
--assignee-object-id "{uamiPrincipalId}" \
--assignee-principal-type ServicePrincipal \
--role "Storage Blob Data Contributor" \
--scope "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}"
Role assignment propagation can take up to 10 minutes. Wait, then retry. If the failure affects a user's access to output files rather than the workspace identity, use Can't view output files.
Container image pull failures
Tool runs fail with ImagePullBackOff. Check that the image repository and tag in the tool definition exist, and that the registry network rules allow access from the supercomputer.
Verify permissions for the supercomputer's kubelet UAMI, which pulls images. In a shared-identity deployment, it can be the same UAMI used by the workspace. For a registry in RBAC Registry Permissions mode, assign AcrPull at the registry scope:
az role assignment create \
--assignee-object-id "{uamiPrincipalId}" \
--assignee-principal-type ServicePrincipal \
--role "AcrPull" \
--scope "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ContainerRegistry/registries/{acrName}"
For an ABAC-enabled registry, use supported repository roles instead. AcrPull isn't a substitute for repository-scoped permissions. See Supercomputer registry access.
Workspace creation fails with identity error
For ManagedIdentityNotFound or LinkedAuthorizationFailed errors:
- Verify the UAMI exists:
az identity show --name {name} --resource-group {rg}. - Verify the identity resource ID and its required placement for your deployment. For cross-region deployments, follow the workload-region placement in Deploy across regions.
- Confirm the caller has Reader access to the identity resource.
See Configure a user-assigned managed identity.
Chat model deployment fails
Agent responses fail with authentication errors when calling Azure OpenAI if the service-managed Cognitive Services OpenAI User assignment is missing.
Find the workspace managed resource group:
az rest --method GET \
--url "https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Discovery/workspaces/{workspaceName}?api-version=2026-06-01" \
--query "properties.managedResourceGroup"
Verify role assignments there. If the autoassigned role is missing, contact Microsoft Support. Don't manually modify assignments managed by the Discovery service.
Persona role assignment script fails
Use the failed and skipped rows in the persona role assignment script summary to identify the affected scope.
| Symptom | Cause and resolution |
|---|---|
FATAL: -ResourceGroupName is required when -Scope is 'ResourceGroup'. |
Supply -ResourceGroupName <name> or choose -Scope Subscription when that broader scope is intended. |
Role 'Microsoft Discovery Bookshelf Index Data Reader - Preview' not found in this tenant. |
The role isn't available in the tenant yet. The run continues; rerun later to pick up the role. |
Azure AI Owner/User ... [-WorkspaceManagedRGName not provided; ...] |
The workspace doesn't exist yet. Follow the two-step assignment workflow, or use subscription scope only if that scope is intended. |
Permission denied from New-AzRoleAssignment |
The script runner needs Owner, User Access Administrator, or Role Based Access Control Administrator at the target scope. |
Unable to acquire token for tenant '...' and User interaction is required |
Specify the subscription's tenant with -TenantId <guid> or enter the tenant GUID at the prompt. |
For additional cross-tenant guidance, see the script troubleshooting reference.
Project access or linked-resource permissions are incorrect
Use the project role verification commands to inspect direct and inherited assignments.
| Symptom | Cause and resolution |
|---|---|
| You can't see a project | Assign the role at the full project resource ID and allow time for Azure RBAC propagation. |
| You can see every project | Review and narrow an inherited Microsoft Discovery Platform role at workspace, resource group, or subscription scope. |
| The tool list is empty or agent creation is denied | Assign Microsoft Discovery Tools Reader (Preview) on each referenced tool or an approved containing scope. |
| The model picker is empty or agent creation is denied | Assign Microsoft Discovery Chat Model Reader (Preview) on the selected model deployment or workspace. |
| A contributor can run an existing agent but can't view its tool or model | This behavior is expected for an agent created by a platform administrator. Add Tools Reader or Chat Model Reader only if the contributor needs to view those definitions or update the agent. |
| Discovery Engine runs without Chat Model Reader | This behavior is expected. Project Contributor authorizes Discovery Engine, and the platform gpt-5-4 deployment doesn't require a separate user assignment. |
| Project artifacts' storage account is inaccessible | Assign Storage Account Contributor on the backing storage account or resource group. |
| Storage assets are visible, but files can't be opened | Assign Storage Blob Data Reader or Storage Blob Data Contributor at the backing Azure Storage scope. Also check the client network and CORS requirements. |
| A knowledge base isn't listed or can't be queried | Assign Microsoft Discovery Bookshelf Index Data Reader - Preview on the bookshelf or an inherited scope. |
| Agent creation worked before a linked-resource role was removed | Access is checked during agent create or update, not every run. Update or remove agents that reference the revoked resource. |
| A project-only user can't read Workbench session status | Some Workbench read and status operations require inherited workspace access because they don't include project context. |
Storage container creation fails or stays in provisioning
If Azure reports that .../storageAccounts/{name} wasn't found, verify storageAccountId is the full ARM ID of an existing storage account. Create the storage account before the Discovery storage container.
For provisioning failures, inspect the storage container operation, backend access, identity permissions, and network path. Storage containers are resource-group-level resources, not workspace children; don't infer their provisioning requirements from workspace state alone. Use Get a storage container to inspect the resource. If the operation remains stuck and doesn't identify a correctable configuration problem, contact Microsoft Support before retrying or recreating it.
For blob permission failures, use Storage access denied.
Tool deployment fails
| Symptom | Cause and resolution |
|---|---|
InvalidDefinitionContent during creation |
Revalidate the YAML against the tool definition reference, then convert it to JSON again. |
| Environment variables aren't visible in the container | Confirm the uploaded file is a flat { "KEY": "value" } JSON object, then recreate the tool resource with that file. |
RoleAssignmentNotFound during creation |
Assign Contributor or Microsoft Discovery Platform Administrator (Preview) at resource group scope. |
ImagePullBackOff during a tool run |
Follow the container image and identity checks. |
See Deploy a tool to Microsoft Discovery for the creation workflow.
Shared sessions or tasks don't make progress
| Symptom | Where to start |
|---|---|
| Tasks stay in New status | Check the Discovery Engine and task dependencies. |
| Tasks finish without useful results | Add specific, achievable validation requirements and set the task back to New. |
| The agent keeps retrying the same approach | Review validation requirements and agent capability. |
| No tasks start after several minutes | Allow 2-3 minutes for startup, then confirm the project has at least one deployed agent. See Cognition warmup. |
| Tool calls take a long time | Compare with normal execution times, including the first-call cold start. |
Logs show a task in FLAGGED_HUMAN state |
Open the shared session in Discovery Studio and address the task that needs attention. |
| CogLoop is waiting for a running tool task | Inspect the associated job in the supercomputer logs. |
| A context-window saturation reset failed | Contact your Discovery administrator with the instance and error details. |
Serialization errors block all cognition instances
An instance's working memory might not deserialize after a model-schema change, or instance data in Cosmos DB might be corrupted.
- Run the serialization-error query to confirm the pattern.
- Inspect
Exceptionfor the JSON path and property that fails. - Escalate to the service team with the instance ID and exception details.
Tasks aren't being validated
- Run the TaskValidationAgent lifecycle query to check provisioning, upsert, and invocation.
- Look for upsert failures or provisioning errors. If there are no entries, first rule out missing or delayed logs, then check whether the validation agent was provisioned.
- Verify the required workspace model deployment using the Discovery Engine startup checks.
Circuit breaker events persist
Repeated model API failures can open a circuit breaker and temporarily pause CogLoop requests. Events normally clear after the cooldown. Use the circuit-breaker query to inspect BrokenCircuitException. If the events persist, contact Microsoft Support.
Resources or tool outputs aren't visible
For files that exist but return access errors, use Can't view output files to check the user's network path, CORS, and storage permissions.
A resource doesn't appear in the conversation
- Call
GetResourceContextto confirm that the resource URI exists in conversation context. - Check whether it is marked as not shared. If so, the agent hasn't called
ShareResource. - Call
PreviewResourceon the URI to confirm it contains content. - If the description is missing, verify
UpdateResourceDetailswas called beforeShareResource. - If the resource is still absent, use Azure Storage Explorer to check whether the file exists under
discoveryOutputs/{projectName}/{investigationName}/{conversationGuid}/.
Tool outputs don't appear in GetResourceContext
- Confirm the tool's output directory is listed in
outputMounts. - Verify the tool succeeded by checking conversation history for errors.
- Confirm each output mount is an absolute directory path, not a file path.
Agent resource calls look incorrect in logs
Agents reason iteratively, so an unsuccessful call followed by a corrected call doesn't necessarily require intervention.
| Log pattern | Interpretation |
|---|---|
PreviewResource returns "resource not found" |
The output might not exist yet, or the URI is wrong. The agent can refresh GetResourceContext and retry with the correct URI. |
Repeated GetResourceContext calls |
The agent is refreshing the resource list after tool execution. |
ShareResource returns "already shared" |
The resource is already visible; the tool returns a success confirmation. |
UpdateResourceDetails follows ShareResource |
The description update doesn't retroactively change the storage asset that was already created. |
Intervene if the agent repeats the same failing call without progress, not merely because it makes a mistake and then self-corrects.
Application logs contain no data
First, confirm you're querying the Log Analytics workspace for the affected resource, not a different managed resource group. Expand the time range to the last 24 hours and allow for ingestion latency. Logs usually arrive within seconds, but ingestion can take up to five minutes.
If the resource has no relevant activity, generate logs by running an appropriate operation:
| Component | Table or query guide | Operation that generates logs |
|---|---|---|
| Workspace | DiscoveryLogs_CL | Run a shared session. |
| Bookshelf queries | DiscoveryLogs_CL | Run a knowledge base query in Discovery Studio. |
| Bookshelf indexing | DiscoveryBookshelfLogs_CL | Create or reindex a knowledge base. |
| Cognition loop | DiscoveryCogLoopLogs_CL | Run a shared session with Discovery Engine. |
| Supercomputer | Supercomputer log tables | Run a shared session or indexing job that uses compute. |
Log queries time out or run slowly
Narrow the time range and filter before aggregating. For cognition logs, filter by InstanceId, LogLevel, or Message. Use take or limit to restrict the result set, or summarize when you need aggregates rather than raw rows.
Activity log entries are missing or show Failed
If entries are missing:
- Extend the time range to cover the operation. Activity logs retain up to 90 days.
- Verify the resource group filter contains the resource, or remove the filter.
- Confirm the operation changed the resource. Read-only HTTP GET requests don't appear in the Activity Log.
For a failed entry, inspect its Properties in the Azure portal or query the error details:
AzureActivity
| where ResourceProviderValue == "MICROSOFT.DISCOVERY"
| where ActivityStatusValue == "Failure"
| extend ErrorCode = tostring(parse_json(Properties).statusCode)
| extend ErrorMessage = tostring(parse_json(Properties).statusMessage)
| project TimeGenerated, OperationNameValue, Caller, ErrorCode, ErrorMessage
| order by TimeGenerated desc
See View activity logs for access and export instructions.
Advanced troubleshooting and data collection
If you create an Azure support request, collect the following information so support can investigate quickly:
- For ARM failures, the correlation ID and deployment operation list; for application failures, the response, timestamp, and available request, conversation, or run identifiers.
- The Activity Log entries and relevant supercomputer, workspace, or bookshelf logs.
- The role assignments on the deploying identity or project managed identity.
- The region, API version, and Toolbox or template version.
- For networking issues, the
nslookupoutput from inside the virtual network, the private endpoint and DNS configuration, and the network security group rules.