Skip to content

Troubleshooting

Jump to bottom
Griffen Fargo edited this page Oct 6, 2025 · 1 revision

This guide covers common issues you might encounter with coco and their solutions. Issues are organized by category for easy navigation.

Quick Diagnostic Commands

Before diving into specific issues, try these diagnostic commands:

# Check coco version and basic info
coco --version

# Verbose output shows detailed processing
coco --verbose commit

# Validate current configuration
coco init --scope project

# Test with minimal config
COCO_VERBOSE=true coco commit

Installation & Setup Issues

"Command Not Found: coco"

Symptoms: bash: coco: command not found or similar

Solutions:

# Check if installed globally
npm list -g git-coco

# If not installed, install globally
npm install -g git-coco

# Check PATH includes npm global bin
npm config get prefix
echo $PATH

# Alternative: Use npx (no installation needed)
npx git-coco@latest commit

# For project-specific installation
npm install --save-dev git-coco
npx coco commit

"Permission Denied" During Installation

Symptoms: EACCES: permission denied during npm install

Solutions:

# Use npx instead (recommended)
npx git-coco@latest init

# Or fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# Or use a Node version manager
# Install nvm, then:
nvm install node
npm install -g git-coco

"Module Not Found" Errors

Symptoms: Various module import errors

Solutions:

# Clear npm cache
npm cache clean --force

# Reinstall coco
npm uninstall -g git-coco
npm install -g git-coco@latest

# Check Node.js version (requires Node 16+)
node --version

# Update Node.js if needed
nvm install --lts
nvm use --lts

API Key & Authentication Issues

"No API Key Found"

Symptoms: No API Key found. 🗝️🚪

Solutions:

# Set via environment variable (temporary)
export OPENAI_API_KEY=sk-your-key-here
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Set via configuration file (permanent)
coco init --scope project

# Verify API key format
# OpenAI: starts with "sk-"
# Anthropic: starts with "sk-ant-"

# Test API key directly
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

"Invalid API Key" or "Unauthorized"

Symptoms: 401 Unauthorized errors

Solutions:

# Verify API key is correct (no extra spaces/characters)
echo "$OPENAI_API_KEY" | wc -c  # Should be ~51 characters

# Check API key permissions and billing
# Visit: https://platform.openai.com/account/billing

# Regenerate API key if needed
# Visit: https://platform.openai.com/api-keys

# Test with curl
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"test"}],"max_tokens":5}' \
  https://api.openai.com/v1/chat/completions

"Rate Limited" or "Quota Exceeded"

Symptoms: 429 Too Many Requests or quota errors

Solutions:

# Check usage and billing limits
# Visit: https://platform.openai.com/account/usage

# Reduce concurrent requests
{
  "service": {
    "maxConcurrent": 1,
    "requestOptions": {
      "timeout": 60000,
      "maxRetries": 2
    }
  }
}

# Use smaller token limits
{
  "service": {
    "tokenLimit": 1024
  }
}

# Switch to different model (if quota per model)
{
  "service": {
    "model": "gpt-3.5-turbo"  // Instead of gpt-4
  }
}

Git & Repository Issues

"Not a Git Repository"

Symptoms: fatal: not a git repository

Solutions:

# Initialize git repository
git init

# Or navigate to existing git repository
cd /path/to/your/git/repo

# Verify you're in a git repository
git status

"No Staged Changes"

Symptoms: No staged changes found or empty commit messages

Solutions:

# Stage your changes first
git add .

# Or stage specific files
git add file1.js file2.js

# Check what's staged
git diff --cached

# If files are already committed, make new changes
echo "// New change" >> file.js
git add file.js

"Working Directory Not Clean"

Symptoms: Git warnings about uncommitted changes

Solutions:

# Stage changes you want to commit
git add .

# Or stash changes temporarily
git stash
# ... use coco ...
git stash pop

# Or commit existing changes first
git commit -m "WIP: temporary commit"

Package Manager Compatibility

pnpm ES Module Issues

Symptoms: Directory import ... is not supported resolving ES modules

Solutions:

# Update commitlint packages to latest
pnpm add -D @commitlint/config-conventional@latest @commitlint/cli@latest

# Or disable commitlint validation temporarily
coco --no-conventional

# Or use npm/yarn instead for coco
npm install -g git-coco

Yarn PnP (Plug'n'Play) Issues

Symptoms: Module resolution errors with Yarn PnP

Solutions:

# Install coco globally instead of in project
npm install -g git-coco

# Or use npx
npx git-coco@latest commit

# Or disable PnP for this project
echo 'nodeLinker: node-modules' >> .yarnrc.yml
yarn install

Conventional Commits & Commitlint Issues

"Commit Message Validation Failed"

Symptoms: Commitlint validation errors

Solutions:

# Check commitlint configuration
cat .commitlintrc.json
# or
cat commitlint.config.js

# Test commitlint directly
echo "feat: test message" | npx commitlint

# Update commitlint packages
npm install --save-dev @commitlint/config-conventional@latest @commitlint/cli@latest

# Disable validation temporarily
coco --no-conventional

# Use interactive mode to edit message
coco -i

"Invalid Conventional Commit Format"

Symptoms: Messages don't follow conventional commits format

Solutions:

# Enable conventional commits mode
coco --conventional

# Or set in configuration
{
  "conventionalCommits": true
}

# Check valid commit types
# feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

# Example valid formats:
# feat: add new feature
# fix(auth): resolve login issue
# feat!: breaking change

"Commitlint Config Not Found"

Symptoms: Commitlint not detecting configuration

Solutions:

# Create commitlint config file
echo 'module.exports = {extends: ["@commitlint/config-conventional"]}' > commitlint.config.js

# Or JSON format
echo '{"extends": ["@commitlint/config-conventional"]}' > .commitlintrc.json

# Install required packages
npm install --save-dev @commitlint/config-conventional @commitlint/cli

# Verify configuration
npx commitlint --help-config

AI Model & Generation Issues

"Model Not Available" or "Model Not Found"

Symptoms: Errors about unavailable models

Solutions:

# Check available models for your provider
# OpenAI models: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo
# Anthropic models: claude-3-5-sonnet-latest, claude-3-haiku-latest

# Update to supported model
{
  "service": {
    "model": "gpt-4o"  // Use current model name
  }
}

# For Ollama, pull the model first
ollama pull qwen2.5-coder:7b

"Request Timeout" or "Connection Issues"

Symptoms: Network timeouts or connection errors

Solutions:

# Increase timeout settings
{
  "service": {
    "requestOptions": {
      "timeout": 120000,  // 2 minutes
      "maxRetries": 3
    }
  }
}

# Check internet connection
curl -I https://api.openai.com

# Check firewall/proxy settings
# Corporate networks may block AI APIs

# For Ollama, check service is running
curl http://localhost:11434/api/version

"Poor Quality Commit Messages"

Symptoms: Generic or unhelpful commit messages

Solutions:

# Add more context
coco --additional "Fixes user login timeout issue"

# Include previous commits for context
coco --with-previous-commits 3

# Use interactive mode to edit
coco -i

# Ignore irrelevant files
coco --ignored-files "*.lock" --ignored-extensions ".map"

# Try different model
{
  "service": {
    "model": "gpt-4o",  // Instead of gpt-3.5-turbo
    "temperature": 0.3  // Lower for more consistent output
  }
}

"JSON Parsing Errors"

Symptoms: Errors parsing AI response as JSON

Solutions:

# Enable verbose mode to see raw response
coco --verbose commit

# Increase parsing attempts for Ollama
{
  "service": {
    "maxParsingAttempts": 5  // Higher for local models
  }
}

# Try different model (some are more reliable)
{
  "service": {
    "model": "gpt-4o"  // More reliable than older models
  }
}

# Check if using latest coco version
npm update -g git-coco

Performance Issues

"Slow Response Times"

Symptoms: Long wait times for commit generation

Solutions:

# Reduce token limits
{
  "service": {
    "tokenLimit": 1024  // Instead of 4096
  }
}

# Ignore large/irrelevant files
{
  "ignoredFiles": ["dist/*", "node_modules/*", "*.lock"],
  "ignoredExtensions": [".map", ".min.js", ".bundle.js"]
}

# Use faster model
{
  "service": {
    "model": "gpt-3.5-turbo"  // Faster than gpt-4
  }
}

# For Ollama, use smaller model
ollama pull qwen2.5-coder:3b  # Instead of 7b or larger

"High Memory Usage"

Symptoms: System slowdown or out-of-memory errors

Solutions:

# Ignore large files and directories
{
  "ignoredFiles": [
    "node_modules/**",
    "dist/**", 
    "build/**",
    "*.{jpg,png,gif,pdf,zip}"
  ]
}

# Use --no-diff for very large changesets
coco --no-diff commit

# For Ollama, use appropriate model size for your RAM
# 8GB RAM: use 3b models
# 16GB RAM: use 7b models
# 32GB+ RAM: use 14b+ models

Configuration Issues

"Configuration Not Loading"

Symptoms: Settings not being applied

Solutions:

# Check configuration priority order:
# 1. Command line flags (highest)
# 2. Environment variables
# 3. .coco.config.json (project)
# 4. .gitconfig
# 5. XDG config (lowest)

# Verify config file syntax
cat .coco.config.json | jq .  # Should parse without errors

# Check environment variables
env | grep COCO

# Test with explicit config
coco --verbose --mode interactive commit

"Invalid Configuration Schema"

Symptoms: Configuration validation errors

Solutions:

# Validate JSON syntax
cat .coco.config.json | jq .

# Check against schema
# Visit: https://git-co.co/schema.json

# Regenerate config with wizard
coco init --scope project

# Common fixes:
{
  "$schema": "https://git-co.co/schema.json",
  "service": {
    "provider": "openai",  // Must be: openai, anthropic, or ollama
    "model": "gpt-4o",     // Must be valid model name
    "authentication": {
      "type": "APIKey",    // Must be: APIKey, OAuth, or None
      "credentials": {
        "apiKey": "sk-..."
      }
    }
  }
}

Environment-Specific Issues

Windows-Specific Issues

Symptoms: Path or permission issues on Windows

Solutions:

# Use PowerShell or Command Prompt as Administrator
# Install with npm (not yarn) on Windows

# For WSL users
wsl --install
# Then install coco inside WSL

# Path issues
npm config get prefix
# Add to PATH in System Environment Variables

# Use npx to avoid installation issues
npx git-coco@latest commit

macOS-Specific Issues

Symptoms: Permission or Gatekeeper issues

Solutions:

# Allow Terminal full disk access
# System Preferences > Security & Privacy > Privacy > Full Disk Access

# Install Xcode Command Line Tools
xcode-select --install

# Use Homebrew for Node.js
brew install node
npm install -g git-coco

Linux-Specific Issues

Symptoms: Permission or dependency issues

Solutions:

# Install Node.js via package manager
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Install coco
npm install -g git-coco

Getting Additional Help

Enable Debug Mode

# Maximum verbosity
COCO_VERBOSE=true coco --verbose commit

# Debug specific components
DEBUG=coco:* coco commit  # If debug logging is implemented

Collect Diagnostic Information

# System information
node --version
npm --version
git --version
coco --version

# Configuration
coco init --scope project  # Shows current config

# Test basic functionality
echo "test" > test.txt
git add test.txt
coco --verbose commit

Report Issues

When reporting issues, include:

  1. System information (OS, Node.js version, package manager)
  2. Coco version (coco --version)
  3. Configuration (sanitized, remove API keys)
  4. Error messages (full error output)
  5. Steps to reproduce (minimal example)
  6. Expected vs actual behavior

GitHub Issues: https://github.com/gfargo/coco/issues Discord Community: https://discord.gg/KGu9nE9Ejx

Emergency Workarounds

If coco is completely broken:

# Use without installation
npx git-coco@latest commit

# Generate commit manually with AI
curl -X POST https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Generate a commit message for: $(git diff --cached)"}],
    "max_tokens": 100
  }'

# Fallback to manual commits
git commit -m "fix: manual commit while debugging coco"

Remember: Most issues can be resolved by updating to the latest version, checking configuration, and ensuring proper API key setup. When in doubt, try the setup wizard: coco init

Clone this wiki locally