Troubleshooting Guide

Common issues and solutions when setting up and using the GitHub Copilot SDK.

Installation Issues
Authentication Issues
Runtime Issues
SDK-Specific Issues
Performance Issues
Platform-Specific Issues

Installation Issues

Issue: `copilot: command not found`

Symptoms:

$ copilot --version
bash: copilot: command not found

Solutions:

Install Copilot CLI extension:
```
gh extension install github/gh-copilot
```
Verify installation:
```
gh extension list
```

Add to PATH (if needed):

# Linux/macOS
export PATH="$PATH:$HOME/.local/bin"

# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc

Windows PATH:
- Add %USERPROFILE%\.local\bin to system PATH
- Restart terminal after PATH change

Issue: `gh: command not found`

Symptoms:

$ gh --version
bash: gh: command not found

Solutions:

macOS:

brew install gh

Linux (Debian/Ubuntu):

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

Windows:

winget install --id GitHub.cli

Issue: Node.js version too old

Symptoms:

Error: Requires Node.js 18 or higher

Solutions:

Install latest Node.js:
- Visit https://nodejs.org/
- Download LTS version (18+)

Using nvm (Node Version Manager):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node 18+
nvm install 20
nvm use 20

Verify version:

node -v  # Should show v18.x.x or higher

Authentication Issues

Issue: GitHub CLI not authenticated

Symptoms:

✗ GitHub CLI is not authenticated

Solutions:

Login to GitHub:
```
gh auth login
```
Follow the prompts:
- Choose "GitHub.com"
- Choose "HTTPS" or "SSH"
- Authenticate via web browser
Verify authentication:
```
gh auth status
```
Refresh Copilot token:
```
gh auth refresh -s copilot
```

Issue: Copilot authentication expired

Symptoms:

Error: Copilot access denied
Error: Authentication token expired

Solutions:

Refresh authentication:
```
gh auth refresh -s copilot
```
Re-login if needed:
```
gh auth logout
gh auth login
```
Verify Copilot access:
- Ensure you have an active Copilot subscription
- Check at: https://github.com/settings/copilot

Runtime Issues

Issue: Port already in use

Symptoms:

Error: Address already in use
Error: EADDRINUSE: address already in use :::8080

Solutions:

SDK handles this automatically - The SDK should find an available port

If issues persist, kill existing processes:

# Find Copilot processes
ps aux | grep copilot

# Kill specific process
kill <PID>

# Or kill all copilot processes (be careful!)
pkill -f copilot

Windows:

# Find process using port
netstat -ano | findstr :8080

# Kill process
taskkill /PID <PID> /F

Issue: CLI server connection timeout

Symptoms:

Error: Timeout waiting for CLI server
Error: Failed to connect to Copilot CLI

Solutions:

Check CLI is working:
```
copilot "hello"
```

Increase timeout in code:

// TypeScript
const client = new CopilotClient({
    startupTimeout: 60000, // 60 seconds
});

Check for antivirus/firewall blocking

Restart CLI server:

pkill -f copilot
# Then restart your application

Issue: Out of memory errors

Symptoms:

JavaScript heap out of memory
MemoryError

Solutions:

Increase Node.js memory (TypeScript):

NODE_OPTIONS="--max-old-space-size=4096" npm start

Optimize session management:
- Close sessions when done
- Limit conversation history
- Use streaming to reduce memory
Python memory optimization:
- Use generators for large datasets
- Implement proper cleanup with await client.stop()

SDK-Specific Issues

TypeScript/Node.js Issues

Module not found

Symptoms:

Cannot find module '@github/copilot-sdk'

Solutions:

Install dependencies:
```
npm install
```

Clear cache and reinstall:

rm -rf node_modules package-lock.json
npm install

Check package.json:

{
  "dependencies": {
    "@github/copilot-sdk": "^0.1.0"
  }
}

TypeScript errors

Symptoms:

TS2304: Cannot find name 'CopilotClient'

Solutions:

Install TypeScript types:
```
npm install --save-dev @types/node
```

Check tsconfig.json:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

Python Issues

Module not found

Symptoms:

ModuleNotFoundError: No module named 'copilot'

Solutions:

Activate virtual environment:

source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

Install package:
```
pip install github-copilot-sdk
```
Verify installation:
```
pip list | grep copilot
```

Async/await issues

Symptoms:

RuntimeWarning: coroutine was never awaited

Solutions:

Use asyncio.run():

import asyncio

async def main():
    # Your async code
    pass

asyncio.run(main())

Ensure all async calls are awaited:

await client.start()
await session.send_and_wait({"prompt": "test"})

Go Issues

Import errors

Symptoms:

cannot find module providing package

Solutions:

Install SDK:
```
go get github.com/github/copilot-sdk/go
```
Update dependencies:
```
go mod tidy
```

Verify go.mod:

require github.com/github/copilot-sdk/go v0.1.0

.NET Issues

Package not found

Symptoms:

error NU1101: Unable to find package GitHub.Copilot.SDK

Solutions:

Add package:
```
dotnet add package GitHub.Copilot.SDK
```
Restore packages:
```
dotnet restore
```
Clear NuGet cache:
```
dotnet nuget locals all --clear
```

Performance Issues

Issue: Slow response times

Solutions:

Use streaming for faster perceived performance:

const session = await client.createSession({
    streaming: true,
});

Choose appropriate model:
- Faster models: gpt-4o
- More capable: gpt-4.1
Reduce context:
- Limit conversation history
- Be specific in prompts

Issue: High CPU/memory usage

Solutions:

Close unused sessions:

await session.close();
await client.stop();

Limit concurrent sessions:

// Keep track and limit active sessions
const MAX_SESSIONS = 5;

Use session pooling for frequent requests

Platform-Specific Issues

macOS Issues

Rosetta 2 on Apple Silicon

If running on Apple Silicon (M1/M2/M3):

# Check if Rosetta is needed
arch

Most tools now have ARM support, but if needed:

softwareupdate --install-rosetta

Linux Issues

Permission denied

Symptoms:

Permission denied: '/usr/local/bin/copilot'

Solutions:

Install to user directory:
```
gh extension install github/gh-copilot
```
Fix permissions:
```
chmod +x ~/.local/bin/copilot
```

Windows Issues

PowerShell execution policy

Symptoms:

cannot be loaded because running scripts is disabled

Solutions:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows Defender blocking

If Windows Defender blocks the CLI:

Add exception for Copilot CLI
Check Windows Security → App & browser control
Add %USERPROFILE%\.local\bin to exclusions

Still Having Issues?

Check system status

GitHub Status: https://www.githubstatus.com/
Copilot Status: Check for known issues

Get help

Run validation script:
```
bash scripts/validate-env.sh
```
Enable debug logging:
```
DEBUG=true
LOG_LEVEL=debug
```
Report issues:
- GitHub Issues: https://github.com/github/copilot-sdk/issues
- Include:
  - Error messages
  - SDK version
  - Platform and version
  - Steps to reproduce

Useful diagnostic commands

# Check versions
gh --version
copilot --version
node -v
python3 --version
go version
dotnet --version

# Check authentication
gh auth status

# Check Copilot CLI
copilot "test"

# Check processes
ps aux | grep copilot

# Check network
ping github.com

Prevention Tips

Keep tools updated:

gh extension upgrade gh-copilot
npm update -g

Use virtual environments (Python):
- Always activate before installing packages
- One environment per project
Use .gitignore:
- Don't commit .env files
- Don't commit node_modules/ or venv/

Regular cleanup:

# Node.js
npm cache clean --force

# Python
pip cache purge

Monitor resources:
- Close unused sessions
- Implement proper error handling
- Use timeouts for operations

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Troubleshooting Guide

Table of Contents

Installation Issues

Issue: copilot: command not found

Issue: gh: command not found

Issue: Node.js version too old

Authentication Issues

Issue: GitHub CLI not authenticated

Issue: Copilot authentication expired

Runtime Issues

Issue: Port already in use

Issue: CLI server connection timeout

Issue: Out of memory errors

SDK-Specific Issues

TypeScript/Node.js Issues

Module not found

TypeScript errors

Python Issues

Module not found

Async/await issues

Go Issues

Import errors

.NET Issues

Package not found

Performance Issues

Issue: Slow response times

Issue: High CPU/memory usage

Platform-Specific Issues

macOS Issues

Rosetta 2 on Apple Silicon

Linux Issues

Permission denied

Windows Issues

PowerShell execution policy

Windows Defender blocking

Still Having Issues?

Check system status

Get help

Useful diagnostic commands

Prevention Tips

Issue: `copilot: command not found`

Issue: `gh: command not found`