AI Troubleshooting
Purpose and Scope
This page gives practical entrypoints for diagnosing AI and agent failures in VS Code. In this context, “AI” means the Copilot-backed editor experiences such as chat, inline assistance, agent mode, and tool execution. “Agent troubleshooting” means collecting enough evidence to distinguish user configuration problems, network or authentication failures, model-service errors, tool-result rendering issues, hook failures, and marketplace or upgrade failures in the agent host. The repository evidence here focuses on how diagnostic data is represented at source level, while the official product documentation supplies the first-run workflow for opening logs and inspecting chat sessions.
The most useful troubleshooting path is layered. Start with product-visible logs and diagnostics, then move into chat-session inspection, then classify the failure using protocol-level error shapes. VS Code’s documentation recommends setting the GitHub Copilot and GitHub Copilot Chat log level to Trace, opening the GitHub Copilot or GitHub Copilot Chat output channel, and collecting diagnostics with the GitHub Copilot: Collect Diagnostics command when connectivity is suspected. For agent-specific sessions, the Agent Debug Log panel and Chat Debug view expose the chronological event stream, prompts, tool calls, model requests, and response payloads that explain what the agent attempted before failing.
Relevant Source Files
extensions/copilot/src/extension/agentDebug/vscode-node/toolResultContentRenderer.ts— renders language-model tool result content into strings for agent debug logging and inspection.src/vs/platform/agentHost/node/codex/protocol/generated/v2/CodexErrorInfo.ts— defines the Codex agent-host error taxonomy, including limits, connectivity, authorization, sandbox, and stream failures.src/vs/platform/agentHost/node/codex/protocol/generated/v2/ErrorNotification.ts— defines the notification envelope that carries a turn error, retry intent, thread id, and turn id.src/vs/platform/agentHost/node/codex/protocol/generated/v2/HookErrorInfo.ts— defines the shape of hook execution failures with a hook path and message.src/vs/platform/agentHost/node/codex/protocol/generated/v2/MarketplaceLoadErrorInfo.ts— defines marketplace-load failures with the marketplace path and message.src/vs/platform/agentHost/node/codex/protocol/generated/v2/MarketplaceUpgradeErrorInfo.ts— defines marketplace-upgrade failures with the marketplace name and message.
First Response Workflow
When a user reports that Copilot or an agent “is not working,” first decide whether the failure is visible before, during, or after a chat turn. Before a turn, likely causes include sign-in state, subscription or enterprise access, network policy, proxy configuration, or disabled settings. During a turn, inspect whether the request reached the model, whether tools ran, and whether a stream disconnected. After a turn, review rendered tool results, edit application, hook behavior, and whether the agent attempted to retry. This ordering avoids treating every symptom as a model-quality issue.
The official troubleshooting workflow begins in the Command Palette. Use Developer: Set Log Level and set Trace for GitHub Copilot and GitHub Copilot Chat, then use Output: Show Output Channels to select the matching channel. If Copilot cannot connect, run GitHub Copilot: Collect Diagnostics to produce an editor tab with network-oriented details that can be reviewed or attached to an issue. For session-level investigation, enable the agent debug log setting described in the docs, open the Agent Debug Logs panel from the Chat view or Command Palette, and use the Chat Debug view when raw prompt, context, request, response, or tool invocation payloads are needed.
Error Taxonomy and Retry Signals
The Codex protocol files show that agent-host failures are not a single generic error string. CodexErrorInfo is a discriminated union of named failure categories: context-window exhaustion, usage limits, overloaded servers, cyber policy, internal server errors, unauthorized requests, bad requests, rollback failures, sandbox errors, non-steerable turns, and other errors. Several connectivity and stream variants also carry an optional httpStatusCode, which is important when correlating the UI symptom with server, provider, proxy, or firewall behavior. Sources: src/vs/platform/agentHost/node/codex/protocol/generated/v2/CodexErrorInfo.ts
ErrorNotification wraps a turn error with operational context: willRetry, threadId, and turnId. Treat those fields as the bridge between a user-facing chat failure and the session timeline. If willRetry is true, the system is already attempting recovery, so repeated reports may be transient or rate-related. If it is false, preserve the thread and turn identifiers when escalating because they identify the failed unit of work. Sources: src/vs/platform/agentHost/node/codex/protocol/generated/v2/ErrorNotification.ts
| Source-level signal | What it usually tells you | First troubleshooting action |
|---|---|---|
usageLimitExceeded | The account or plan hit an allowance boundary | Check Copilot plan, quota, or enterprise policy before debugging prompts |
contextWindowExceeded | The request exceeded model context capacity | Reduce attached files, prompt size, or workspace context |
unauthorized | Authentication or entitlement failed | Recheck GitHub sign-in, Copilot access, and organization policy |
httpConnectionFailed | Request setup or upstream connectivity failed | Collect diagnostics and review proxy, firewall, or VPN behavior |
responseStreamDisconnected | The response stream dropped mid-turn | Compare output logs with Chat Debug request and retry behavior |
sandboxError | Execution environment failed | Inspect tool, workspace, and sandbox-related entries in the agent log |
Agent Debug Rendering Details
Tool calls are central to agent mode, so troubleshooting often depends on whether the tool result is readable in logs. ToolResultContentRenderer implements the debug renderer for tool result content by iterating over content parts and producing string output. Text parts are copied directly, prompt TSX parts are serialized as formatted JSON when possible, and data parts are delegated to renderDataPartToString. This is intentionally lightweight: the implementation avoids expensive asynchronous prompt rendering because it runs on every tool call. Sources: extensions/copilot/src/extension/agentDebug/vscode-node/toolResultContentRenderer.ts
That implementation detail matters when interpreting Agent Debug Log output. A missing or abbreviated tool result does not always mean the tool returned no information; it can mean the content part was not one of the rendered language-model part types or that prompt TSX serialization fell back to the placeholder [PromptTsxPart]. When debugging a custom tool or extension-provided agent workflow, compare the raw Chat Debug payload with the rendered log text. If the raw payload is complete but the rendered view is compact, the issue is likely in display or serialization expectations rather than in the model request itself.
Hooks, Marketplace, and Extension-like Failures
Agent workflows can fail outside the model call. HookErrorInfo records a failing hook by path and message, which makes hook issues traceable to the configured lifecycle file or script rather than to the model response. If a user reports that an agent stops at a predictable phase, ask for the Agent Debug Log around that phase and look for hook path information. The path is the actionable clue: it tells the investigator which local customization or lifecycle integration should be reviewed first. Sources: src/vs/platform/agentHost/node/codex/protocol/generated/v2/HookErrorInfo.ts
Marketplace-related failures have separate source-level shapes. MarketplaceLoadErrorInfo carries a marketplacePath plus a message, while MarketplaceUpgradeErrorInfo carries a marketplaceName plus a message. The distinction is useful: load failures point at a concrete local path, while upgrade failures point at a named marketplace package or integration. In practice, that means a load error should trigger file existence, permissions, and local configuration checks; an upgrade error should trigger version, package availability, or compatibility checks. Sources: src/vs/platform/agentHost/node/codex/protocol/generated/v2/MarketplaceLoadErrorInfo.ts, src/vs/platform/agentHost/node/codex/protocol/generated/v2/MarketplaceUpgradeErrorInfo.ts
Compact Reference
| Component | Public shape or behavior visible in source | Troubleshooting use |
|---|---|---|
ToolResultContentRenderer.renderToolResultContent(content: Iterable<unknown>): string[] | Converts recognized language-model text, prompt TSX, and data parts into strings | Explains what should appear in agent debug logs after tool calls |
CodexErrorInfo | Union of named agent-host error categories and HTTP-aware connection variants | Classifies failures before choosing network, quota, auth, sandbox, or prompt-size remediation |
ErrorNotification | { error: TurnError, willRetry: boolean, threadId: string, turnId: string } | Correlates a failed turn with retry behavior and session identifiers |
HookErrorInfo | { path: string, message: string } | Locates hook-related failures in customization files or scripts |
MarketplaceLoadErrorInfo | { marketplacePath: AbsolutePathBuf, message: string } | Points investigation at a local marketplace path |
MarketplaceUpgradeErrorInfo | { marketplaceName: string, message: string } | Points investigation at a named marketplace integration or package |
Next Steps
For a routine support case, collect three artifacts before escalating: the Copilot or Copilot Chat output channel at Trace level, the diagnostics editor produced by GitHub Copilot: Collect Diagnostics when connectivity is involved, and the relevant Agent Debug Log or Chat Debug view export for the failed session. Then classify the symptom against the protocol categories above and preserve thread, turn, hook, marketplace, and HTTP status details when present. Related pages to read next are copilot-and-ai-overview for capability boundaries, chat-view for the main AI surface, chat-sessions for persistence and session inspection, chat-tools-and-approvals for tool execution boundaries, and agent-monitoring-opentelemetry for deeper agent observability.