Coach

Troubleshooting & FAQs

Common issues, solutions, and frequently asked questions

Installation Issues

"Package not found" errors during installation

This usually occurs when using an outdated package index or when behind a firewall.

Solution:

bash
# Update package index first
npm cache clean --force
npm install

# For Python backend
pip install --upgrade pip
pip install -r requirements.txt

Next.js build fails with TypeScript errors

This can happen when TypeScript definitions are out of sync or when using incompatible versions.

Solution:

bash
# Remove node_modules and reinstall
rm -rf node_modules .next
npm install

# Fix TypeScript issues
npx tsc --noEmit

Python dependency conflicts

Dependency conflicts can occur when installing the Python backend.

Solution:

bash
# Create a fresh virtual environment
python -m venv venv_new
source venv_new/bin/activate  # On Windows: venv_new\Scripts\activate

# Install with --no-cache-dir
pip install --no-cache-dir -r requirements.txt

API Connection Issues

"Failed to connect to API" error

This error occurs when the frontend cannot communicate with the backend API.

Check:

  1. Ensure the backend server is running and accessible at the configured URL
  2. Verify that CORS is properly configured on the backend
  3. Check that the API URL in your environment variables is correct

Solution:

bash
# Verify API is running
curl http://localhost:8000/api/health

# Check environment variables
echo $NEXT_PUBLIC_API_URL

GitHub API rate limit exceeded

GitHub limits the number of API requests you can make within a certain time period.

Solution:

  • Use a GitHub personal access token with higher rate limits
  • Implement caching to reduce the number of API requests
  • Wait for the rate limit to reset (usually 1 hour)
bash
# Check your current rate limit status
curl -H "Authorization: token YOUR_GITHUB_TOKEN" https://api.github.com/rate_limit

Gemini API errors

Issues connecting to or getting responses from the Gemini API.

Solution:

  • Verify your API key is valid and has sufficient permissions
  • Check that you're using the correct endpoint for the Gemini API
  • Ensure your prompts don't violate any content policies
python
# Test Gemini API connectivity
import os
import google.generativeai as genai

api_key = os.environ.get("GEMINI_API_KEY")
genai.configure(api_key=api_key)

model = genai.GenerativeModel('gemini-pro')
result = model.generate_content("Test message to verify API connectivity")
print(result.text)

Scanning Issues

Scan takes too long or times out

Large repositories can take a long time to scan, sometimes exceeding timeout limits.

Solution:

  • Increase the timeout setting in the configuration file
  • Scan specific directories instead of the entire repository
  • Use the CLI with the --incremental flag to only scan changed files
bash
# Scan only a specific directory
coach scan --path=src/

# Use incremental scanning
coach scan --incremental

Too many false positives

The scanner may sometimes flag code that isn't actually vulnerable.

Solution:

  • Adjust the sensitivity levels in the configuration file
  • Add specific exclusion patterns for known false positives
  • Use the feedback mechanism to improve the detection engine
yaml
# Example configuration to reduce false positives
sensitivity: medium
exclude_patterns:
  - "**/*.test.js"
  - "**/mock_data/*.sql"

Scan fails with "Out of memory" error

Very large repositories or files can exceed the available memory when scanning.

Solution:

  • Increase the memory allocation for the Node.js process
  • Use the --max-file-size option to skip very large files
  • Break the scan into smaller chunks by scanning subdirectories separately
bash
# Increase Node.js memory limit
NODE_OPTIONS=--max-old-space-size=8192 coach scan

# Limit file size for scanning
coach scan --max-file-size=10MB

Frequently Asked Questions

How often should I scan my repositories?

We recommend integrating scanning into your CI/CD pipeline to scan on every pull request. Additionally, schedule regular full scans weekly to catch vulnerabilities that might have been missed.

Is my code data sent to Gemini API?

Only code snippets related to detected vulnerabilities are sent to the Gemini API for analysis and fix generation. We strip sensitive information and context to maintain security. You can configure the tool to completely avoid sending certain types of files or code patterns.

Does Coach work with private repositories?

Yes, Coach works with both public and private repositories. For private repositories, you'll need to provide appropriate GitHub authentication credentials. We recommend using a GitHub App or personal access token with the minimal permissions required.

Can I use Coach in an air-gapped environment?

Yes, Coach supports air-gapped deployments for security-sensitive environments. In this mode, the AI-powered fix generation features will be limited, but all vulnerability detection capabilities will work locally. Contact our support team for detailed deployment instructions for air-gapped environments.

How do I exclude certain files from scanning?

You can exclude files or directories using patterns in the configuration file:

yaml
# .coach.yaml
exclude:
  - "**/*.min.js"
  - "**/node_modules/**"
  - "**/vendor/**"
  - "**/*.test.js"
  - "**/*.spec.js"

Can I customize the vulnerability rules?

Yes, Coach allows you to customize vulnerability detection rules. You can adjust sensitivity levels, disable specific rule types, or add custom detection patterns. These settings can be configured in the .coach.yaml file in your repository root or through the web interface for global settings.

Getting Additional Help

If you're still experiencing issues, there are several ways to get help:

GitHub Issues

Report bugs or request features through our GitHub repository.

Open an Issue

Email Support

For urgent issues or private concerns, contact our support team directly.

Email Support