Azure Cosmos DB Shell troubleshooting guide

Gëllt fir: ✅ NoSQL

Resolve common issues with Azure Cosmos DB Shell installation, authentication, connections, and command execution.

Installation issues

Issue: "Command not found" (NuGet installation)

Error:

cosmosdbshell: command not found

Causes:

.NET SDK not installed
Tool not installed correctly
PATH not updated
Terminal not restarted after installation

Solutions:

Verify .NET SDK Installation
```
dotnet --version
```
- Should show version 10.0 or later
- If not installed, install .NET SDK

Reinstall the Tool

dotnet tool uninstall --global CosmosDBShell
dotnet tool install --global CosmosDBShell --prerelease

Verify Installation Location
```
dotnet tool list --global | grep CosmosDBShell
```
- Should show: cosmosdbshell 1.0.213-preview
Restart Terminal
- Close and reopen your terminal
- Terminal may cache PATH information
Add to PATH Manually (if needed)
- Windows: Add %USERPROFILE%\.dotnet\tools to PATH
- macOS/Linux: ~/.dotnet/tools should already be in PATH

Issue: "File not found" (binary installation)

Error:

cosmosdbshell: No such file or directory

Causes:

Archive didn't extract completely
File not executable (Linux/macOS)
Wrong file path

Solutions:

Verify Extraction
- Check all files were extracted
- Look for cosmosdbshell executable (or .exe on Windows)
Make Executable (Linux/macOS)
```
chmod +x ~/cosmosdbshell/cosmosdbshell
```
Use Full Path
```
/full/path/to/cosmosdbshell
```
Add to PATH
```
export PATH="$PATH:~/cosmosdbshell"
```

Issue: "File corrupted" during download

Error:

Archive is corrupted or incomplete

Causes:

Incomplete download
Network interruption
Wrong file format

Solutions:

Download Again
- Delete corrupted file
- Re-download from official source
- Verify file size matches expected
Check MD5/SHA Hash
- Compare hash of downloaded file
- Matches hash provided on release page
Use Different Browser
- Try alternative download method
- Try different network connection

Authentication issues

Issue: "Authentication failed"

Error:

Authentication failed. Please check your credentials.

Causes:

Expired token
Wrong credentials
No internet connection
Account key incorrect

Solutions:

Try Entra ID (Recommended)
- Cosmos DB Shell should prompt for browser authentication
- Sign in with your Azure account
- Most reliable method
Check Internet Connection
```
ping azure.microsoft.com
```
- Ensure network connectivity
Verify Account Key
- Go to Azure portal
- Navigate to Cosmos DB account
- Copy Primary Connection String
- Verify format is correct
Clear Cached Credentials
- Windows: credman (Credential Manager)
- macOS: Keychain
- Linux: Check ~/.config directory

Issue: "Unauthorized - insufficient permissions"

Error:

Authorization failed. Your user does not have permission to perform this operation.

Causes:

User lacks necessary RBAC roles
Role not assigned to account
Wrong subscription context

Solutions:

Check RBAC Roles
- Go to Azure portal > Cosmos DB Account
- Access Control (IAM)
- Verify your user has "Cosmos DB Account Reader" or higher role
Request Role Assignment
- Ask your subscription admin
- Assign appropriate role (see Security Best Practices)
Verify Subscription
```
az account show
```
- Ensure you're in correct subscription
- Switch if needed: az account set --subscription <ID>

Issue: "Token expired"

Error:

Token has expired. Please re-authenticate.

Causes:

Session timeout
Token expired after long inactivity
Time synchronization issue

Solutions:

Re-authenticate
- Exit shell: exit
- Restart: cosmosdbshell
- Sign in again
Check System Time
- Ensure system clock is synchronized
- Windows: Settings > Time & Language > Date & Time
- macOS/Linux: Check system time with date
Check Token Refresh Settings
- Tokens should auto-refresh
- If issue persists, contact Azure support

Connection issues

Issue: "Connection refused"

Error:

Connection refused to Cosmos DB account

Causes:

Wrong endpoint URL
Firewall blocking connection
Network connectivity issue
Account endpoint incorrect

Solutions:

Verify Endpoint URL
- Azure portal > Cosmos DB Account
- Copy correct endpoint URL
- Format: https://<account>.documents.azure.com:443/
Check Firewall
- Verify IP allowed in Cosmos DB firewall rules
- Azure portal > Cosmos DB Account > Firewall and virtual networks
- Add your IP if needed
Test Network Connectivity
```
ping <account>.documents.azure.com
```
- Should respond with IP address
Check VPN/Proxy
- If using VPN, ensure it's connected
- If using proxy, verify proxy settings

Issue: "Cannot resolve endpoint"

Error:

Cannot resolve host: account.documents.azure.com

Causes:

DNS resolution failure
Wrong endpoint name
Network connectivity
Firewall blocking DNS

Solutions:

Verify Endpoint Spelling
- Double-check account name
- Correct format: https://<account>.documents.azure.com:443/
Check DNS
```
nslookup <account>.documents.azure.com
```
- Should return IP address
Try Alternative DNS
- Use public DNS (8.8.8.8, 1.1.1.1)
- Check ISP DNS settings
Test Direct Connection
```
telnet <account>.documents.azure.com 443
```
- Should connect successfully

Issue: "Timeout connecting to Cosmos DB"

Error:

Connection timeout. Could not connect to Cosmos DB account.

Causes:

Network latency
Slow internet connection
Cosmos DB service issue
Firewall blocking traffic

Solutions:

Increase Timeout
- Modify connection timeout in settings
- Default is 30 seconds
Check Network Speed
- Test bandwidth with speed test
- Ensure sufficient bandwidth
Try Different Network
- Switch to different Wi-Fi or mobile hotspot
- Test if issue is network-specific
Check Azure Status
- Go to Azure Status Page
- Verify Cosmos DB service is operational

Command issues

Issue: "Command not recognized"

Error:

Unknown command. Type 'help' for available commands.

Causes:

Typo in command name
Command not supported in current version
Using wrong syntax

Solutions:

Check Command Syntax
- Use help to list available commands
- Use help <command> for specific command help
Verify Command Spelling
```
> help query
```
- Correct: query, not select or find
Check Your Version
```
> version
```
- Ensure you have latest version

Issue: "Syntax error in query"

Error:

Syntax error in SQL query

Causes:

Invalid SQL syntax
Missing quotes
Incorrect JSON path
Unsupported SQL function

Solutions:

Review SQL Syntax
- Verify query is valid SQL (not NoSQL)
- Example: SELECT * FROM c WHERE c.status = 'active'
- Not valid: db.collection.find({})
Check String Quotes
- Use single quotes in queries
- String values: 'value'
- JSON keys: "key"
Validate JSON Path
- Correct: c.address.city
- Not valid: c.address[0].city (without proper syntax)
Test Query in Azure portal
- Verify query works in Data Explorer first
- Copy working query to shell

Issue: "No documents returned"

Error:

CS > query "SELECT * FROM c"
(empty result)

Causes:

Container is empty
Query filter too restrictive
Wrong container
Partition key mismatch

Solutions:

Verify Container Has Data
```
> query "SELECT COUNT(*) as count FROM c"
```
- Should return count > 0
Check Container Name
```
> pwd
```
- Verify you're in correct container

Simplify Query

# Start with simple query
> query "SELECT TOP 1 * FROM c"

# Then add filters
> query "SELECT * FROM c WHERE c.status = 'active'"

Review Partition Key
- Ensure partition key is included in query
- For better performance: SELECT * FROM c WHERE c.id = 'value'

VS Code extension issues

Issue: Extension not appearing

Error:

Cannot find "Azure Cosmos DB Shell" in Extensions

Causes:

VS Code version too old
Extension not installed
VS Code cache issue

Solutions:

Check VS Code Version
- Help > About
- Should be 1.85 or later
- Update if needed
Reinstall Extension
- Go to Extensions (Ctrl+Shift+X)
- Search "Cosmos DB"
- Click Install
Clear VS Code Cache
- Close VS Code
- Delete .vscode folder in user directory
- Restart VS Code

Issue: Resource Explorer blank

Error:

Resource Explorer shows no databases or containers

Causes:

Not authenticated
No Cosmos DB accounts in subscription
Wrong subscription selected
Account has no databases

Solutions:

Verify Authentication
- Click Cosmos DB icon in sidebar
- Should show account selector
- Sign in if prompted
Check Subscription
- Verify correct subscription is selected
- Switch subscription if needed
Refresh Explorer
- Press F5 or click refresh icon
- Wait for data to load
Check Account Exists
- Go to Azure portal
- Verify Cosmos DB account exists
- Verify you have access to account

Issue: MCP server won't start in VS Code

Error:

Failed to start MCP server

Causes:

Port already in use
Invalid settings
Cosmos DB Shell not properly installed
Firewall blocking port

Solutions:

Check Port Availability

# Windows
netstat -ano | findstr 6128

# macOS/Linux
lsof -i :6128

If in use, kill process or use different port

Verify MCP Settings
- Open Settings (Ctrl+,)
- Search "Cosmos DB"
- Check cosmosDB.shell.MCP.enabled is true
Try Different Port
```
{
  "cosmosDB.shell.MCP.port": 6129
}
```
Check Firewall
- Ensure firewall allows localhost connections
- Disable temporarily to test

MCP server issues

Issue: "MCP server not responding"

Error:

Cannot connect to MCP server

Causes:

MCP server not running
Wrong port
Firewall issue
Connection timeout

Solutions:

Verify MCP Server Running
```
curl http://localhost:6128/health
```
- Should return JSON response
Check Configuration
- Verify cosmosDB.shell.MCP.enabled is true
- Check correct port in settings
Restart MCP Server
- Command Palette (Ctrl+Shift+P)
- Type "Cosmos DB: Restart MCP Server"
Check Firewall
- Ensure localhost:6128 is accessible
- Disable firewall temporarily to test

Issue: "MCP port already in use"

Error:

Cannot bind MCP server to port 6128

Causes:

Another process using port
MCP server already running
Port conflict

Solutions:

Stop Existing MCP Server
- Command Palette (Ctrl+Shift+P)
- Type "Cosmos DB: Stop MCP Server"

Find Process Using Port

# Windows
netstat -ano | findstr 6128
taskkill /PID <PID> /F

# macOS/Linux
lsof -i :6128
kill -9 <PID>

Use Different Port
```
{
  "cosmosDB.shell.MCP.port": 6129
}
```

Performance issues

Issue: Shell is slow or unresponsive

Causes:

Large query result set
Slow network connection
High system resource usage
Cosmos DB service issue

Solutions:

Limit Query Results
```
> query "SELECT TOP 100 * FROM c"
```

Add Filters to Query

> query "SELECT * FROM c WHERE c.status = 'active'"

Check Network
- Test bandwidth
- Switch to different network
- Check latency with ping
Monitor System Resources
- Check CPU usage
- Check memory usage
- Close unnecessary applications

Issue: Queries timeout

Error:

Query timeout. Please try again.

Causes:

Large result set
Complex query
Slow network
Cosmos DB service overloaded

Solutions:

Increase Timeout Setting
- Settings (Ctrl+,)
- Search "Cosmos DB"
- Increase cosmosDB.queryTimeout

Optimize Query

# Instead of SELECT *
> query "SELECT c.id, c.name FROM c"

# Add filters
> query "SELECT * FROM c WHERE c.status = 'active'"

# Use TOP
> query "SELECT TOP 1000 * FROM c"

Check Cosmos DB
- Verify service is operational
- Check Azure Status Page

Getting help

Check Docs
Azure Support
- For Cosmos DB service issues: Create support request

Feedback

War dës Säit hëllefräich?

Last updated on 2026-05-06

Azure Cosmos DB Shell troubleshooting guide

Installation issues

Issue: "Command not found" (NuGet installation)

Issue: "File not found" (binary installation)

Issue: "File corrupted" during download

Authentication issues

Issue: "Authentication failed"

Issue: "Unauthorized - insufficient permissions"

Issue: "Token expired"

Connection issues

Issue: "Connection refused"

Issue: "Cannot resolve endpoint"

Issue: "Timeout connecting to Cosmos DB"

Command issues

Issue: "Command not recognized"

Issue: "Syntax error in query"

Issue: "No documents returned"

VS Code extension issues

Issue: Extension not appearing

Issue: Resource Explorer blank

Issue: MCP server won't start in VS Code

MCP server issues

Issue: "MCP server not responding"

Issue: "MCP port already in use"

Performance issues

Issue: Shell is slow or unresponsive

Issue: Queries timeout

Getting help

See also

Feedback

Zousätzlech Ressourcen