Troubleshooting Scenario Questions

Increase the confidence threshold parameter in the analyzeDocument request body to 0.99.

Why it fails: The confidence threshold only filters which extracted fields the response returns; raising it to 0.99 suppresses low-confidence results rather than improving the model's accuracy. It is tempting as a quick quality gate, which suits downstream validation logic, not raising the underlying extraction confidence of a custom template model.

Convert all training PDFs to grayscale and reduce their resolution to 72 DPI to speed up processing.

Why it fails: Grayscale conversion and 72 DPI reduction strip colour and detail the custom template model relies on to match field layouts, degrading extraction confidence further. It is tempting because smaller files process faster, which suits latency or throughput optimisation, not accuracy on poorly extracted fields.

Switch the model type from custom template to a prebuilt business card model.

Why it fails: A prebuilt business card model extracts a fixed schema of contact fields and cannot target the custom fields the template model was trained on, so those fields lose extraction entirely. It is tempting because prebuilt models need no training, which suits standard documents such as business cards, not bespoke field extraction.

Listen for incoming webhook notifications on an Azure Event Grid subscription attached to the text analytics resource.

Why it fails: Azure AI Language LROs expose status through the Operation-Location polling URL; no Event Grid subscription is created for the /analyze job. It is tempting because Event Grid delivers push notifications for resource events, but it is correct only where an event source publishes to a subscribed topic.

Query the Azure Monitor metrics API for job completion status.

Why it fails: Azure Monitor exposes resource metrics and diagnostic logs, not the per-job operation status or result payload of an LRO. It is tempting because Azure Monitor tracks service health and latency, but it is correct only for monitoring resource-level telemetry, not for retrieving a specific job's output.

Repeatedly send synchronous POST requests to the same document endpoint until a 200 OK is returned.

Why it fails: The /analyze endpoint returns an Operation-Location header; status and results are retrieved by polling that operation URL with GET, not by resubmitting documents. It is tempting because polling is the right pattern, but re-POSTing re-runs the job and returns 202 Accepted, never the completed summary payload.

Switch from General domain to Food domain.

Why it fails: Domain selection changes the training data prior for food versus general imagery; it does not add occlusion examples, so partially hidden objects remain undetected. It is tempting because domain choice does affect accuracy, and would be correct if the images were food-related and misclassified by category rather than occluded.

Lower the confidence threshold to 0.01.

Why it fails: Lowering the confidence threshold to 0.01 admits near-random detections, producing false positives rather than genuinely detecting occluded objects. It is tempting because it does increase recall, and would be correct if the model already detected the objects but filtered them out just below the existing threshold.

Increase image compression artifacts.

Why it fails: Adding compression artifacts degrades image quality, removing the visual features needed to recognise partially occluded objects. It is tempting because augmentation can improve robustness, and would be correct if the goal were training-time augmentation with varied distortions, not deliberately corrupting inference images.

Change the system prompt to ignore safety.

Why it fails: Overriding the system prompt removes the safety instructions that triggered the block, so the harmful content is served rather than investigated. It appeals because system prompts shape model behaviour, and editing them is correct when tuning tone or persona — not when diagnosing a Content Safety severity threshold hit.

Increase the model temperature.

Why it fails: Temperature governs sampling randomness in token selection; it has no bearing on the Content Safety filter that returned 'Blocked'. It is tempting because temperature tuning is the right lever when outputs are repetitive or overly deterministic, but the block originates outside the model's decoding step.

Disable Content Safety for the deployment.

Why it fails: Disabling Content Safety removes the filter entirely, so the offending category is never surfaced and the deployment loses its guardrail. It appeals as a quick unblock, and would be correct only in an isolated test deployment where filtering genuinely obstructs evaluation and no production traffic is exposed.

Double the model temperature to 2.0 to accelerate reasoning speed.

Why it fails: Temperature accepts values from 0 to 2, so 2.0 is valid but increases output randomness and token generation length, worsening timeouts rather than accelerating reasoning. It is tempting because temperature is the familiar knob for tuning model behaviour, and lowering it would be correct when diagnosing verbose or unstable agent responses.

Delete all vector indices to force local memory processing.

Why it fails: Deleting vector indices removes the retrieval grounding agents depend on, so tool calls fail or return nothing and timeouts persist. It is tempting because local memory processing sounds like it bypasses network round trips, and rebuilding an index would be correct when embeddings are stale or dimensionally mismatched.

Run the Azure Advisor cost recommendation analyzer to optimize resource pricing tiers.

Why it fails: Cost optimisation reports analyse spending against usage, offering no visibility into network path, firewall rules or DNS resolution. It is tempting because Azure Advisor surfaces resource recommendations, and would be correct for reducing waste, but connectivity faults require Network Watcher, IP flow verify and connection troubleshoot instead.

Use the Azure Resource Manager template visualizer to inspect regional resource dependencies.

Why it fails: Template visualiser renders ARM deployment topology and dependencies, not live packet flow or firewall rule evaluation. It is tempting because it clarifies resource relationships, and would be correct when auditing deployment structure, but intermittent connectivity demands runtime diagnostics such as connection monitor and NSG flow logs.

Delete all project iteration history to reset model weights to random initialization.

Why it fails: Deleting iterations removes trained snapshots and their performance metrics; it does not reset weights to random initialisation, and it destroys the evidence needed to compare models. It is tempting as a clean-slate remedy, but retraining with additional labelled images is the actual mechanism for improving a poorly performing detector.

Manually edit model neural network weights via the REST API.

Why it fails: Custom Vision exposes training, prediction and iteration endpoints; no REST API permits editing neural network weights, which are learned internally during training. It is tempting because the REST API does allow programmatic control of projects, and it would be correct for automating training, publishing or exporting an iteration as a model.

The system prompt length.

Why it fails: Prompt length affects token processing at the model, and you have already confirmed model response time is fine. Retrieval latency stems from the vector store query, embedding call, or index configuration, so investigate those instead.

The content safety threshold.

Why it fails: Content safety filtering adds a classification step on prompts and completions, not on the retrieval query itself. It becomes relevant when outputs are blocked or flagged; slow retrieval points to the search backend, embedding generation, or index size.

The model temperature.

Why it fails: Temperature changes sampling randomness in the model's output distribution and has no effect on retrieval duration. It is tuned for creativity versus determinism; the slow step here is the search or embedding call, not decoding.

Use the Read API instead

Why it fails: The Read API returns recognised text and bounding boxes but does not reconstruct table structure, so it cannot resolve cells being merged or columns misread. It is tempting because Read is the standard call for plain text extraction, and it would be the right choice for documents containing no tabular layout.

Disable the layout model

Why it fails: Disabling the layout model removes the component that detects and reconstructs table structure, worsening the misinterpretation rather than fixing it. It is tempting because switching off a misbehaving feature feels like a quick remedy, and it would be correct when layout analysis actively harms non-tabular documents.

Change the resource region

Why it fails: Changing the resource region relocates the Azure AI Document Intelligence resource; it does not alter how tables are parsed, so misread cells persist. It is tempting because region selection affects latency and data residency, and it would be the right action when compliance or performance requires a different deployment location.

The model weights have become corrupted and require redeployment.

Why it fails: Corrupted model weights cause consistent failures or degraded output, not intermittent 429 responses tied to request-rate spikes. Redeployment is the right choice when a deployment returns persistent errors or malformed completions regardless of traffic volume.

The Azure subscription has run out of monthly financial budget.

Why it fails: Budget exhaustion suspends the subscription or disables the resource, yielding authorisation or deployment errors rather than intermittent 429s that clear as traffic subsides. Budget alerts are the right choice for cost governance, not for diagnosing per-deployment rate limiting.

The Private Endpoint DNS resolution has failed.

Why it fails: Private Endpoint DNS failure blocks name resolution entirely, producing connection errors rather than HTTP 429, and it would not correlate with request-rate spikes. Private Endpoint DNS is the right choice to diagnose when requests fail to reach the deployment at all.

Increase the vector index size

Why it fails: Retrieval already returns the correct documents, so enlarging the vector index adds no grounding benefit and may dilute precision. The failure lies in generation, so prompt engineering or fine-tuning to enforce context use is required. Index sizing is tempting because retrieval quality often causes errors, but that is not this symptom.

Use a smaller base model

Why it fails: Retrieval is already correct, so the failure lies in generation, not model capacity; shrinking the model reduces its ability to follow retrieved context and synthesise an accurate answer. Smaller base models suit latency- or cost-constrained deployments where the task is simple, not grounding fixes.

Disable streaming response

Why it fails: Streaming governs token delivery to the client, not how retrieved context is reasoned over. The model already receives correct documents but misuses them, so grounding must be improved through prompt design or fine-tuning. Disabling streaming is tempting for debugging output, but it changes no generation accuracy.

Restart the client web browser session

Why it fails: Restarting the browser session clears client state but cannot reveal why the agent's tool invocation fails server-side. Browser restarts suit stale cached UI or authentication cookie issues; diagnosing tool invocation requires inspecting agent traces, tool schemas and API request logs in Azure AI Foundry.

Increase the Azure DNS TTL value for domain resolution

Why it fails: DNS TTL governs how long resolvers cache records; it has no bearing on whether an agent invokes a tool. Raising it would only delay propagation of DNS changes. TTL tuning belongs to scenarios involving DNS failover or record migration, not tool-call debugging in Azure AI Foundry.

Verify that the client application has been assigned the Storage Blob Data Contributor role.

Why it fails: Storage Blob Data Contributor governs Blob Storage data-plane access, not Azure AI Language connectivity through a Private Endpoint. It is tempting because role assignments commonly cause authorisation failures, and this role would be correct when an application must read or write blobs in a storage account.

Ensure that the Azure OpenAI model weights have been retrained.

Why it fails: Retraining Azure OpenAI model weights has no bearing on Private Endpoint connectivity; the failure is network-path related, not model quality. It is tempting because retraining addresses accuracy degradation in deployed models, which would be the right action when predictions drift — not when clients cannot reach the resource at all.

Check that public network access is set to enabled and unrestricted.

Why it fails: Enabling unrestricted public access contradicts the Private Endpoint design, which routes traffic privately; the fix lies in private DNS resolution and subnet configuration. It tempts because public access restores connectivity when private DNS zones are misconfigured, but that bypasses the intended private-only posture.

Increase the Azure OpenAI model temperature parameter to 1.5

Why it fails: Temperature controls sampling randomness in generation, not retrieval; raising it to 1.5 makes answers less grounded and cannot improve which chunks are returned. It is tempting because temperature tuning genuinely helps creative or diverse generation, but irrelevant retrieval is fixed by chunking, embeddings, and search configuration.

Configure Azure Key Vault access policies for the search service

Why it fails: Key Vault access policies govern secret storage permissions; they do not affect indexing, embeddings, or ranking, so retrieval relevance is untouched. It is tempting because Key Vault genuinely secures the search service's API keys and connection strings, which is a security concern rather than a retrieval-quality one.

Increase the timeout threshold in the HTTP client configuration.

Why it fails: Raising the HTTP timeout only lets the client wait longer for the same cross-region round trips; it cannot reduce the West US to Southeast Asia network distance causing the latency. Timeout tuning suits slow-processing operations, not geographically misplaced resources, where recreating the Azure AI Vision resource in West US removes the delay.

Enable Azure ExpressRoute between West US and Southeast Asia.

Why it fails: ExpressRoute provides dedicated private connectivity between your on-premises network and Azure, not accelerated routing between two Azure regions; the West US to Southeast Asia distance remains. ExpressRoute suits hybrid connectivity or bypassing public internet paths, whereas this scenario needs the Azure AI Vision resource recreated in West US.

Switch from REST API to gRPC protocol.

Why it fails: gRPC changes serialisation and transport framing, not the physical distance between West US and Southeast Asia, so inter-region round-trip latency persists. gRPC suits high-throughput streaming or compact binary payloads; here the fix is recreating the Azure AI Vision resource in West US alongside the application.