Azure Cosmos DB Shell troubleshooting guide

Start with read-only diagnostics and identify the failing layer before changing credentials, account permissions, network rules, or software installations.

Start with diagnostics

Inside the shell, run:

version
doctor --no-update-check --format=json
whoami

doctor runs bounded checks without changing the connection, navigation, or settings, and works while disconnected. Review each passed, warning, failed, or skipped result. A skipped probe doesn't establish that the account is healthy or that access is allowed.

To explicitly test a selected container, replace the resource names:

doctor --database=MyDatabase --container=MyContainer --query --no-update-check
can-i query --database=MyDatabase --container=MyContainer

These query probes consume RUs. doctor --arm explicitly requests an Azure Resource Manager check. The default update check performs a bounded public GitHub release lookup; --no-update-check disables that lookup. Diagnostics don't initiate interactive authentication for their probes.

Use doctor who for known credential and selected-scope information. whoami describes available identity information, not assigned RBAC roles.

Installation issues

If your operating-system terminal can't find cosmosdbshell:

  1. Determine whether you installed an extension-managed shell, a .NET global tool, or a downloaded binary. An extension-managed shell isn't necessarily on terminal PATH.

  2. For a global tool, run:

    dotnet --list-sdks
    dotnet tool list --global
    

    The global-tool installation requires .NET SDK 10.0 or later. Check whether CosmosDBShell appears in the tool list.

  3. Check that the tool directory is on PATH: %USERPROFILE%\.dotnet\tools on Windows or $HOME/.dotnet/tools on macOS and Linux. Open a new terminal after a persistent PATH change.

  4. For a binary installation, use the full executable path and verify that the downloaded archive matches your operating system and CPU architecture. Self-contained packages include the runtime; _fdd_ packages require it separately.

  5. For an extension-managed installation, run Launch Azure Cosmos DB Shell and follow its installation or repair prompts.

If an archive is incomplete, download that specific archive again from the official releases. Don't remove unrelated extension folders or clear credential stores to diagnose an installation error.

For installation and update commands, see Install Azure Cosmos DB Shell.

Authentication and permissions

Sign-in fails or selects the wrong identity

Check whoami and the credential-related doctor results. A default credential chain can select a different identity than expected.

For explicit interactive tenant authentication, connect inside the shell:

connect https://<account-name>.documents.azure.com/ --tenant=<tenant-id>

Replace the account name and tenant ID and complete the browser sign-in. Then review info --format=json at the account root to confirm the intended accountId and uri.

For managed identity, verify that the shell runs in a supported Azure environment and that the intended identity is enabled and authorized. Use --managed-identity=<client-id> for a user-assigned identity.

Don't paste keys, access tokens, or connection strings into support tickets or chat. Reconnection changes shared MCP state and invalidates pending confirmations, so coordinate with other clients.

Authorization fails

Separate authentication from authorization. A successful sign-in doesn't grant data access.

  • Use can-i read or a scoped can-i query to investigate data-plane access.
  • Review Azure Cosmos DB native data-plane roles for data operations. A management-plane account Reader assignment alone doesn't grant document-query permission.
  • Review separate management-plane permissions for Azure Resource Manager operations.
  • Confirm that the assigned principal, scope, tenant, and intended account match.

can-i write is a heuristic based on delete access, not certification of every write operation. can-i manage is always indeterminate; the command doesn't safely prove management access.

Tokens expire

Review the credential type and sanitized diagnostic result. Token-based credentials can refresh, but a static token can't be refreshed by the shell. Check your machine's time synchronization, then reconnect through the appropriate authentication flow if needed. Don't delete credential stores as a first step.

Network and endpoint issues

For DNS, TLS, or connection failures:

  1. Compare the configured endpoint with the account endpoint in the Azure portal.
  2. Run doctor and identify whether DNS, TLS, authentication, or access failed.
  3. Check that your machine has the required VPN or private-network connectivity.
  4. Check account firewall rules and private-endpoint DNS with your network administrator.
  5. Verify proxy settings where applicable, without disabling TLS validation or opening public access as a workaround.

The shell doesn't bypass account network restrictions. A ping failure alone doesn't establish that the HTTPS data endpoint is unavailable. For private endpoints, don't switch to a public DNS resolver as a generic repair.

For the local emulator, use the documented localhost endpoint and emulator setup. An arbitrary hostname containing the text localhost isn't treated as a local emulator.

Command and query issues

A command or option isn't recognized

Run version, help, and help <command> in the same shell instance. Compare the installed version with the release notes.

Current commands include print for point reads, replace for document replacement, and patch for field changes. Container creation takes a positional partition-key path, such as mkcon Items /tenantId; it doesn't use an invented -pk creation flag.

Use query --max, not --max-items, for a query result bound. Continuation tokens are MCP structured arguments, not interactive query flags.

A query fails or returns no items

Verify the account and explicit resource names, and sample the actual schema before choosing field names:

schema --database=MyDatabase --container=MyContainer --sample=20
query "SELECT TOP 1 c.id FROM c" --database=MyDatabase --container=MyContainer --max=1

The query language is Azure Cosmos DB's NoSQL dialect, not MongoDB syntax or unrestricted relational SQL. Check property casing, value types, quoting, and supported functions.

For a known exact item, use print with both ID and complete partition key. A numeric key, a numeric-looking string key, null, and undefined are different values. print doesn't silently fall back to a query.

A query is slow or consumes too many RUs

Bound output, project required fields, and use filters on verified properties. --max bounds returned items, not the total work or cost of every query.

Use query --explain to inspect first-page execution and observed index metrics. It consumes RUs and isn't a complete execution plan or full-query performance measurement. Missing metrics don't prove that the engine performed a scan.

Check account throughput and throttling as well as network connectivity. Increasing client concurrency doesn't increase provisioned throughput. There isn't a shell-specific cosmosDB.queryTimeout extension setting to repair these issues.

Import, bulk, and write failures

import and bulk aren't transactions across the entire job. Earlier successful writes remain committed, and in-flight writes can finish after an error.

  • Inspect the structured result, counts, representative error, and observed charge before retrying.
  • Use import --dry-run to validate input offline. Success doesn't prove that the target accepts its keys, permissions, IDs, or service constraints.
  • Use --concurrency=1 for imports that must process repeated IDs in file order.
  • Use a bulk journal to distinguish succeeded, failed, and uncertain operations. Don't use --retry-uncertain until you assess whether replay can duplicate effects.
  • On an ETag mismatch, stop and inspect the changed item. Don't remove the condition or refresh the ETag automatically.
  • For batch, verify that every operation belongs to the same complete partition key and that the batch fits supported operation and service limits.

For command syntax and transaction semantics, see Transactions and bulk operations.

Visual Studio Code issues

  • Launch command missing. Confirm the Microsoft Azure Cosmos DB extension, ID ms-azuretools.vscode-cosmosdb, is installed and enabled. Run Launch Azure Cosmos DB Shell.
  • Wrong shell version. Check cosmosDB.shell.path and run version in the launched shell. That copy can differ from the one on your terminal's PATH.
  • Explorer or query editor works but shell doesn't. Verify the shell's connection independently. Don't assume the editor and shell share credentials or navigation.
  • MCP setting changed but no server appears. Exit a shell launched without MCP and relaunch after enabling cosmosDB.shell.MCP.enabled.

See Visual Studio Code integration for the supported settings.

MCP server issues

A client can't connect

Confirm that the shell is running with MCP enabled. An independently launched process requires:

cosmosdbshell --mcp

Use Streamable HTTP at http://127.0.0.1:6128/, or /sse for a legacy SSE client. Verify MCP initialization and tool discovery through the client. The shell isn't a stdio server and doesn't provide a /health REST check.

If the port is occupied, leave the unrelated process alone and choose another port:

cosmosdbshell --mcp 6129

Update the client URL to match. For an extension-launched shell, use cosmosDB.shell.MCP.port instead and relaunch.

A tool is unavailable or refuses execution

Inspect the discovered tool schema. sproc, udf, trigger, watch, and stateful batch/bulk subcommands aren't available through MCP.

Destructive operations fail without the required user confirmation. A changed connection or navigation also invalidates a pending approval. Re-verify the intended target; don't bypass a refusal through another execution route.

Results are incomplete or calls wait

MCP query and item list results are paged. Pass a non-null continuationToken unchanged as continuation with the same options. A null token with resultIncomplete: true means truncation that can't be resumed. Narrow the request or increase its bound.

Calls share the shell's execution gate. Check for an outstanding confirmation or long-running command rather than increasing client parallelism. Legacy SSE can return HTTP 429 for excessive outstanding requests. Honor Retry-After.

Get help

For shell defects, report the installed version, operating system, installation method, sanitized error, and relevant diagnostic verdicts in the shell issue tracker. Review reports for secrets, resource names, and document data before sharing them.

For account-side service issues, use Azure support. Include only the diagnostic information appropriate for your organization's support process.

AI tools

Use these actions to discuss symptoms and sanitized diagnostics with your assistant.

For documentation-only retrieval, use the Microsoft Learn MCP server. For a compact guide index, use the Shell documentation index (llms.txt). The index doesn't change crawler permissions or guarantee retrieval.

Shell MCP requires separate setup and can read or change data under the configured permissions, so review tool calls before approving them. Don't share credentials or sensitive data.

Connect your AI agent
Check Shell MCP setup and authentication requirements.

Read as Markdown
Open a text version to copy into your assistant.

Ask ChatGPT
Diagnose symptoms using versions and sanitized errors.

Ask Claude
Diagnose symptoms using versions and sanitized errors.

ChatGPT and Claude receive only the public article URL and a starter prompt. You might need to sign in. If retrieval fails, copy the Markdown text. These links don't configure database access. Confirm a diagnosis with relevant logs and checks before changing your configuration.