Troubleshooting

Installation Issues

Command not found: ntcli

NPM Installation Issues

Symptoms: ntcli: command not found after running npm install -g @nimbletools/ntcliCause: NPM global bin directory not in PATHSolutions:

Check NPM global bin location:

npm config get prefix 
# Should be in your PATH 

Add NPM global bin to PATH:

# Add to ~/.bashrc, ~/.zshrc, etc. 
export PATH=$(npm config get prefix)/bin:$PATH 

Verify installation:

which ntcli ntcli
--version

Permission Errors

Symptoms: EACCES permission denied errors during installationCause: NPM trying to write to system directoriesSolutions:

Configure NPM to use user directory (recommended):

mkdir ~/.npm-global 
npm config set prefix '~/.npm-global' 
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc 
source ~/.bashrc npm install -g @nimbletools/ntcli 

Use Node Version Manager (recommended):

# Install nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash 
# Install and use Node.js 
nvm install node 
nvm use node 
npm install -g @nimbletools/ntcli

Old Version After Update

Symptoms: ntcli --version shows old version after updateCause: Multiple installations or cached binaries Solutions:

Clear NPM cache:

npm cache clean --force

Complete reinstall:

npm uninstall -g @nimbletools/ntcli
npm install -g @nimbletools/ntcli

Check installation location:

which ntcli ls -la $(which ntcli)

Authentication Issues

Browser Doesn't Open

Symptoms: Browser doesn’t automatically open during ntcli auth loginSolutions:

Manual browser opening:

ntcli auth login --verbose
# Copy the URL from the output and open manually

Check default browser:

# macOS
defaults read com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers

# Linux - check $BROWSER variable
echo $BROWSER

Use alternative browser:

# Set browser temporarily
export BROWSER=firefox
ntcli auth login

Port Already in Use

Symptoms: Error: listen EADDRINUSE: address already in use :::41247Solutions:

Use different port:
```
ntcli auth login --port 8080
```

Find process using port:

# Find process using port 41247
lsof -i :41247

# Kill process if safe to do so
kill -9 <PID>

Set default port:

export NTCLI_DEFAULT_PORT=8080
ntcli auth login

Timeout During Authentication

Symptoms: Authentication times out before completionSolutions:

Increase timeout:

ntcli auth login --timeout 120000  # 2 minutes

Check network connectivity:

curl -I https://clerk.nimbletools.ai
ping clerk.nimbletools.ai

Disable firewall/proxy temporarily:

# Test without proxy
unset http_proxy https_proxy
ntcli auth login

Token and Credential Issues

Authentication Expired

Symptoms: Authentication token expired or 401 UnauthorizedSolutions:

Re-authenticate:

ntcli auth logout ntcli auth login

Refresh workspace tokens:

ntcli token refresh

Check token status:

ntcli auth status 
ntcli token show

Workspace Issues

Workspace Sync and Access Problems

Workspaces Missing Locally

Symptoms: Can’t see or access workspaces that exist on the serverSolutions:

Check workspace sync status:
```
ntcli workspace sync
```
Get access tokens for missing workspaces:
```
ntcli token refresh <workspace-name>
```
Verify workspace is now available:
```
ntcli workspace list
```

Workspace Storage Issues

Symptoms: Workspace commands failing or behaving unexpectedlySolutions:

Debug local workspace storage:
```
ntcli workspace debug
```
Check for detailed file contents (if needed):
```
ntcli workspace debug --verbose
```
Compare local and server state:
```
ntcli workspace sync
```
Fix authentication issues:
```
ntcli auth logout
ntcli auth login
```

Token Expiration Issues

Symptoms: ntcli workspace debug shows expired tokensSolutions:

Check token status:
```
ntcli workspace debug
```
Refresh expired tokens:
```
ntcli token refresh <workspace-name>
```

Verify all workspaces are accessible:

ntcli workspace list
ntcli workspace sync

Workspace Creation Problems

Invalid Workspace Name

Symptoms: Invalid workspace name format errorCause: Workspace name violates naming rulesSolution: Follow naming conventions:

# ❌ Invalid names 
ntcli workspace create "my project"
# spaces 
ntcli workspace create my_project 
# underscores
ntcli workspace create very-long-workspace-name-here 
# too long 
ntcli workspace create my-project!
# special chars 
# ✅ Valid names 
ntcli workspace create my-project # good
ntcli workspace create data-science-2024 # good ntcli workspace create
prod-env # good

Workspace Already Exists

Symptoms: Workspace name already exists error Solutions:

List existing workspaces:

ntcli workspace list

Use different name:

ntcli workspace create my-project-v2

Switch to existing workspace:

ntcli workspace switch my-project

Workspace Quota Exceeded

Symptoms: Workspace quota exceeded errorSolutions:

Check current workspaces:

ntcli workspace list

Delete unused workspaces:

ntcli workspace delete old-workspace --force

Server Deployment Issues

Deployment Failures

Server Not Found in Registry

Symptoms: Server 'xyz' not found in registrySolutions:

Check available servers:

ntcli registry list

Search for similar names:

ntcli registry list | grep -i keyword

Get exact server ID:

ntcli registry show server-name

Deployment Timeout

Symptoms: Deployment hangs or times outSolutions: 1. Check deployment status:

ntcli server list
ntcli server info server-name

View deployment logs:

ntcli server logs server-name --lines 50

Retry deployment:

ntcli server remove server-name --force
ntcli server deploy server-name

Resource Quota Exceeded

Symptoms: Resource quota exceeded during deploymentSolutions:

Check current resource usage:

ntcli server list

Scale down or remove unused servers:

ntcli server scale server-name 1 
ntcli server remove unused-server

Runtime Issues

Server Not Responding

Symptoms: MCP calls fail with connection errorsSolutions:

Check server status:

ntcli server info server-name
ntcli server logs server-name --lines 20

Test MCP connection:

ntcli mcp connect server-name --verbose

Restart server (scale to 0 then back up):

ntcli server scale server-name 0
sleep 10
ntcli server scale server-name 1

Missing Environment Variables

Symptoms: Server logs show missing required environment variablesSolutions:

Check required secrets:

ntcli registry show server-name
# Look for required environment variables

Set missing secrets:

ntcli secrets set API_KEY=your-key-here
ntcli secrets set DATABASE_URL=postgres://...

Restart server after setting secrets:

ntcli server scale server-name 0
ntcli server scale server-name 1

MCP Integration Issues

Claude Desktop Integration

Claude Can't Find MCP Server

Symptoms: Claude Desktop doesn’t show MCP tools or shows connection errorsSolutions:

Verify server is running:

ntcli server list
ntcli server info server-name

Test MCP connection directly:

ntcli mcp connect server-name
ntcli mcp tools server-name

Regenerate Claude Desktop config:

ntcli server claude-config server-name --insecure
# Copy output to claude_desktop_config.json

Restart Claude Desktop after config changes

MCP HTTP Bridge Issues

Symptoms: @nimbletools/mcp-http-bridge connection failuresSolutions:

Test bridge manually:

npx @nimbletools/mcp-http-bridge \
  --endpoint "https://mcp.nimbletools.ai/v1/workspaces/your-workspace/servers/server-name/mcp" \
  --token "your-token" \
  --insecure

Check network connectivity:

curl -H "Authorization: Bearer your-token" \
  "https://mcp.nimbletools.ai/v1/workspaces/your-workspace/servers/server-name/mcp"

Clear npx cache (if bridge seems outdated):

npx clear-npx-cache
# or
rm -rf ~/.npm/_npx

SSL Certificate Issues

Symptoms: SSL certificate errors in Claude Desktop or MCP bridge Solutions: 1. Use —insecure flag for development: bash ntcli server claude-config server-name --insecure 2. Update system certificates: bash # macOS brew install ca-certificates # Linux sudo apt update && sudo apt install ca-certificates 3. Check certificate validity: bash openssl s_client -connect mcp.nimbletools.ai:443 -servername mcp.nimbletools.ai

Network and Connectivity Issues

API Connection Problems

Connection Timeout

Symptoms: ETIMEDOUT or ECONNREFUSED errorsSolutions:

Check API endpoint:

echo $NTCLI_API_URL
curl -I $NTCLI_API_URL/health

Test DNS resolution:

nslookup mcp.nimbletools.ai
ping mcp.nimbletools.ai

Check firewall/proxy settings:

# Temporarily disable proxy
unset http_proxy https_proxy
ntcli health

Proxy Configuration

Symptoms: Connection issues in corporate networksSolutions:

Configure proxy settings:

export http_proxy=http://proxy.company.com:8080
export https_proxy=http://proxy.company.com:8080
export no_proxy=localhost,127.0.0.1

NPM proxy configuration:

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

Test connectivity:
```
ntcli health --verbose
```

Performance Issues

Slow Operations

Slow Server Deployment

Symptoms: Server deployment takes unusually longSolutions:

Check network connection:

curl -w "@curl-format.txt" -o /dev/null -s $NTCLI_API_URL/health

Monitor deployment progress:

ntcli server deploy server-name --verbose --wait

Use smaller resource limits:

ntcli server deploy server-name --cpu "100m" --memory "128Mi"

Slow MCP Calls

Symptoms: MCP tool calls take a long time to respondSolutions:

Check server logs for errors:

ntcli server logs server-name --lines 50

Scale up server resources:
```
ntcli server scale server-name 2
```

Test MCP call timing:

time ntcli mcp call server-name tool-name --arg key=value

Debug and Diagnostic Commands

Collecting Debug Information

# Node.js and NPM versions
node --version
npm --version

# ntcli version and location
ntcli --version
which ntcli

# Environment variables
env | grep NTCLI

Enable Global Debug Mode

For comprehensive debugging across all commands:

export NTCLI_DEBUG=1
export NODE_ENV=development

# All ntcli commands will now show debug output
ntcli auth status
ntcli server list
ntcli mcp tools server-name

Getting Help

If you’re still experiencing issues after trying these solutions:

GitHub Issues

Report bugs or request features on our GitHub repository

Community Slack

Get help from the community and NimbleTools team

Documentation

Browse command documentation and examples

Best Practices

When Reporting Issues

Please include the following information:

Environment
Error Details
Steps to Reproduce

# System information
uname -a
node --version
npm --version
ntcli --version

# Environment variables
env | grep NTCLI

Most issues can be resolved by re-authenticating (ntcli auth logout && ntcli auth login) or updating to the latest version (npm update -g @nimbletools/ntcli).

Platform Architecture

Integrations

Advanced Topics

Examples

Installation Issues

Command not found: ntcli

Authentication Issues

Token and Credential Issues

Workspace Issues

Workspace Sync and Access Problems

Workspace Creation Problems

Server Deployment Issues

Deployment Failures

Runtime Issues

MCP Integration Issues

Claude Desktop Integration

Network and Connectivity Issues

API Connection Problems

Performance Issues

Slow Operations

Debug and Diagnostic Commands

Collecting Debug Information

Enable Global Debug Mode

Getting Help

GitHub Issues

Community Slack

Documentation

Best Practices

When Reporting Issues

Platform Architecture

Integrations

Advanced Topics

Examples

​Installation Issues

​Command not found: ntcli

​Authentication Issues

​OAuth Login Problems

​Token and Credential Issues

​Workspace Issues

​Workspace Sync and Access Problems

​Workspace Creation Problems

​Server Deployment Issues

​Deployment Failures

​Runtime Issues

​MCP Integration Issues

​Claude Desktop Integration

​Network and Connectivity Issues

​API Connection Problems

​Performance Issues

​Slow Operations

​Debug and Diagnostic Commands

​Collecting Debug Information

​Enable Global Debug Mode

​Getting Help

GitHub Issues

Community Slack

Documentation

Best Practices

​When Reporting Issues

Installation Issues

Command not found: ntcli

Authentication Issues

OAuth Login Problems

Token and Credential Issues

Workspace Issues

Workspace Sync and Access Problems

Workspace Creation Problems

Server Deployment Issues

Deployment Failures

Runtime Issues

MCP Integration Issues

Claude Desktop Integration

Network and Connectivity Issues

API Connection Problems

Performance Issues

Slow Operations

Debug and Diagnostic Commands

Collecting Debug Information

Enable Global Debug Mode

Getting Help

When Reporting Issues