# Troubleshooting Guide
> Common issues and solutions for Octocode MCP and Research Skill
## Quick Diagnostics
Run this command to check your environment:
```bash
npx node-doctor info
```
This will diagnose common Node.js issues and let your AI agent help resolve them automatically.
---
## Table of Contents
- [1. npm Registry Issues](#1-npm-registry-issues)
- [2. Node.js Version & Process Issues](#2-nodejs-version--process-issues)
- [3. Authentication Issues](#3-authentication-issues)
- [4. MCP Server Connection Issues](#4-mcp-server-connection-issues)
- [5. Still Having Issues?](#5-still-having-issues)
---
## 1. npm Registry Issues
### Symptom: `npm ERR! 404 Not Found` or slow/hanging installs
If you're behind a VPN or using a private npm registry, the default npm registry may not be accessible.
### Check Your Current Registry
```bash
npm config get registry
```
**Expected output:** `https://registry.npmjs.org/`
### Solutions
#### A. Reset to Default Registry
```bash
npm config set registry https://registry.npmjs.org/
```
#### B. Using a Private Registry
If your organization uses a private registry (e.g., Artifactory, Verdaccio, GitHub Packages):
```bash
# Set your private registry
npm config set registry https://your-private-registry.company.com/
# Or use scoped registries for specific packages
npm config set @your-org:registry https://npm.pkg.github.com/
```
#### C. VPN-Related Issues
If you're on a corporate VPN:
1. **Check if registry is blocked:**
```bash
curl -I https://registry.npmjs.org/
```
2. **Try with proxy settings:**
```bash
npm config set proxy http://your-proxy:8080
npm config set https-proxy http://your-proxy:8080
```
3. **Or bypass SSL verification (not recommended for production):**
```bash
npm config set strict-ssl false
```
#### D. Clear npm Cache
Sometimes cache corruption causes issues:
```bash
npm cache clean --force
```
---
## 2. Node.js Version & Process Issues
### Recommended: Let Your AI Agent Handle It
Run the diagnostic tool and share the output with your AI agent:
```bash
npx node-doctor info
```
**Your AI agent will automatically:**
- Diagnose version compatibility issues
- Identify PATH and environment problems
- Detect conflicting Node.js installations
- Suggest and apply the correct fixes
Simply paste the output into your conversation and let the agent resolve it.
### What the Diagnostic Checks
| Check | Description |
|-------|-------------|
| Node.js version | Minimum 18.12.0 required |
| npm version | Minimum 8.0.0 required |
| PATH configuration | Ensures Node is accessible |
| Multiple installations | Detects nvm, homebrew, system conflicts |
| Permission issues | Identifies npm/node_modules ownership problems |
### Manual Verification (if needed)
```bash
node --version # Should be >= 18.12.0
npm --version # Should be >= 8.0.0
which node # Check which Node is being used
which npm # Should match Node installation
```
### MCP Config: Ensure Node is Found
If MCP server can't find Node, add PATH to your config:
```json
{
"mcpServers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"],
"env": {
"PATH": "/usr/local/bin:/opt/homebrew/bin:$PATH"
}
}
}
}
```
Or use an absolute path:
```json
{
"mcpServers": {
"octocode": {
"command": "/usr/local/bin/npx",
"args": ["octocode-mcp@latest"]
}
}
}
```
---
## 3. Authentication Issues
> **Full authentication guide:** [Authentication Setup](../packages/octocode-mcp/docs/AUTHENTICATION_SETUP.md)
### Quick Auth Check
```bash
# Using Octocode CLI (recommended)
npx octocode-cli
# Select "Check GitHub Auth Status"
# Or check GitHub CLI directly
gh auth status
```
### Common Issues
#### "No GitHub token found"
1. **Run the CLI:**
```bash
npx octocode-cli
# Select "Login to GitHub"
```
2. **Or use GitHub CLI:**
```bash
gh auth login
```
3. **Check environment variable:**
```bash
echo $GITHUB_TOKEN
```
#### "Token expired"
```bash
# Refresh via Octocode CLI
npx octocode-cli
# Select "Login to GitHub"
# Or refresh via GitHub CLI
gh auth refresh
```
#### "Bad credentials" or "401 Unauthorized"
1. **Verify token is valid:**
```bash
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user
```
2. **Check token scopes:**
- Token needs: `repo`, `read:user`, `read:org`
- Create new token at: https://github.com/settings/tokens
#### GitLab Authentication
```bash
# Check GitLab token
echo $GITLAB_TOKEN
# Test GitLab connection
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://gitlab.com/api/v4/user"
```
For self-hosted GitLab, also set:
```bash
export GITLAB_HOST="https://gitlab.your-company.com"
```
---
## 4. MCP Server Connection Issues
### Server Not Starting
#### Check if server is running
```bash
# For Research Skill
curl http://localhost:1987/health
# Check process
ps aux | grep octocode
```
#### Common Fixes
1. **Port already in use:**
```bash
# Find process using port
lsof -i :1987
# Kill it
kill -9 <PID>
```
2. **Restart MCP client:**
- **Cursor:** Cmd/Ctrl + Shift + P → "Reload Window"
- **Claude Desktop:** Quit and relaunch
- **VS Code:** Restart extension host
3. **Check MCP configuration:**
```json
{
"mcpServers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"]
}
}
}
```
---
## 5. Still Having Issues?
If your issue persists after trying the solutions above:
1. **Search existing issues:** [github.com/bgauryy/octocode-mcp/issues](https://github.com/bgauryy/octocode-mcp/issues)
2. **Report a new issue:** Include diagnostic output (`npx node-doctor info`), your environment details, and steps to reproduce
We actively monitor and respond to issues!
