Troubleshooting Guide

This guide covers common issues you might encounter when using Kospex and their solutions.

kgit Clone Issues

kgit failed to clone repository

If kgit clone fails, here are the most common causes and solutions:

Authentication Issues

Problem: Clone fails with authentication errors for private repositories

Solution: Ensure Git Credential Manager is installed and configured:

# Install via Homebrew (recommended)
brew install git-credential-manager

# Or configure Git credentials manually
git config --global credential.helper manager-core

For GitHub: Set up a Personal Access Token with repository access
For Bitbucket: Configure app passwords or OAuth

Network and SSL Issues

Problem: Clone fails with SSL certificate or network errors

Solution:

# Check Git SSL settings
git config --global http.sslVerify true

# For corporate networks, you might need to configure proxy
git config --global http.proxy http://proxy.company.com:8080

Private Certificate Authority (CA) Issues

Problem: Clone fails with SSL certificate verification errors in corporate environments using private CAs

Solutions:

Option 1: Add Private CA Certificate to Git (Recommended)

# Find your private CA certificate file (usually .crt or .pem)
# Add the CA certificate to Git's certificate bundle
git config --global http.sslCAInfo /path/to/your/private-ca.crt

# Or append to system CA bundle (macOS example)
cat /path/to/your/private-ca.crt >> /usr/local/etc/openssl/cert.pem

Option 2: Configure Git to Use System Certificate Store

# On macOS, use system keychain
git config --global http.sslCAInfo /etc/ssl/cert.pem

# On Linux systems
git config --global http.sslCAInfo /etc/ssl/certs/ca-certificates.crt

Option 3: Git Credential Manager, Private CAs and CURL failures Git Credntial Manager can call bitbucket or git servers to detect the server type When it can’t find it, it default to lauching the UI for the credentials

If Curl doesn’t have a CA bundle set, it will error, even if you’ve configured your Git SSL certificates The following allows you to use the CA bundle for curl to stop erroring.

  # Environment variable for CURL
  #
  export CURL_CA_BUNDLE=/path/to/your/ca-bundle.crt

Option 4: Add CA Certificate to System Store

  # macOS - Add to system keychain
  sudo security add-trusted-cert -d -r trustRoot -k /System/Library/Keychains/SystemRootCertificates.keychain /path/to/your/private-ca.crt

  # Or add to login keychain
  security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain /path/to/your/private-ca.crt

  # Linux (Ubuntu/Debian)
  sudo cp /path/to/your/private-ca.crt /usr/local/share/ca-certificates/
  sudo update-ca-certificates

  # Linux (RHEL/CentOS)
  sudo cp /path/to/your/private-ca.crt /etc/pki/ca-trust/source/anchors/
  sudo update-ca-trust

Option 4: Repository-Specific CA Configuration

  # Configure CA certificate for specific repository URL
  git config --global http."https://your-git-server.company.com/".sslCAInfo /path/to/your/private-ca.crt

  # Or disable SSL verification for specific host (less secure)
  git config --global http."https://your-git-server.company.com/".sslVerify false

Temporary Workaround (Not Recommended for Production)

  # Disable SSL verification globally (INSECURE - use only for testing)
  git config --global http.sslVerify false

  # Re-enable SSL verification after fixing CA issues
  git config --global http.sslVerify true

Verifying CA Certificate Installation

  # Test SSL connection to your git server
  openssl s_client -connect your-git-server.company.com:443 -servername your-git-server.company.com

  # Check current Git SSL configuration
  git config --list | grep ssl

  # Test clone with verbose output
  GIT_CURL_VERBOSE=1 git clone https://your-git-server.company.com/repo.git

Directory Permission Issues

Problem: Cannot write to the clone destination directory

Solution:

# Check KOSPEX_CODE directory permissions
ls -la ~/code/

# Fix permissions if needed
chmod -R 755 ~/code/

Invalid Repository URL

Problem: Repository URL is malformed or repository doesn’t exist

Solution: Verify the URL format and repository accessibility:

# Test clone directly with git first
git clone https://github.com/owner/repo /tmp/test-repo

Kospex Common Issues

Database Issues

Database Schema Outdated

Problem: Database operations fail with schema-related errors
Solution:
```
kospex upgrade-db
```

Database Permission Errors

Problem: Cannot write to ~/kospex/kospex.db

Solution:

# Check permissions
ls -la ~/kospex/

# Fix permissions
chmod 644 ~/kospex/kospex.db
chmod 755 ~/kospex/

Sync Issues

Repository Sync Failures

Problem: kospex sync fails on a repository

Solution:

# Check if directory is a valid git repository
cd /path/to/repo && git status

# Try syncing with verbose logging
kospex --debug sync /path/to/repo

# Check logs for detailed error information
tail -f ~/kospex/logs/kospex.log

scc Binary Not Found

Problem: File type analysis and complexity metrics are missing

Solution:

# Install scc via Homebrew
brew install scc

# Or check if scc is in PATH
which scc

Authentication and Rate Limiting

GitHub Rate Limits

Problem: GitHub API requests are being rate limited

Solution:

# Set GitHub token for higher rate limits
export GITHUB_TOKEN=your_github_token_here

# Or add to your shell profile
echo 'export GITHUB_TOKEN=your_token' >> ~/.bashrc

Bitbucket Authentication

Problem: Bitbucket API requests fail with authentication errors

Solution:

# Set Bitbucket credentials
export BITBUCKET_USERNAME=your_username
export BITBUCKET_PASSWORD=your_app_password

Web Interface Issues

Web Server Won’t Start

Port Already in Use

Problem: Cannot bind to port 8000 or 5000

Solution:

# Use a different port
python kweb2.py --port 8080

# Or find what's using the port
lsof -i :8000

Missing Static Assets

Problem: Web interface loads but styling/JavaScript is broken

Solution:

# Rebuild frontend assets
npm install
npm run build

Environment and Setup Issues

Directory Structure Problems

KOSPEX_CODE Directory Issues

Problem: Repositories aren’t being found in expected locations

Solution:

# Check current configuration
kospex init --validate

# Recreate directory structure
kospex init --create

# Set custom code directory
export KOSPEX_CODE=/path/to/your/code

Logging Issues

No Log Output

Problem: Expected log messages aren’t appearing

Solution:

# Enable debug logging
kospex --debug COMMAND

# Enable console logging
kospex --log-console COMMAND

# Check log files directly
ls -la ~/kospex/logs/
tail -f ~/kospex/logs/kospex.log

Log Directory Permission Denied

Problem: Cannot write to log directory

Solution:

# Create and fix log directory permissions
mkdir -p ~/kospex/logs
chmod 755 ~/kospex/logs

Getting Help

If you continue to experience issues:

Check logs: Always check ~/kospex/logs/ for detailed error information
Run with debug: Use --debug flag for verbose output
Validate setup: Run kospex init --validate to check your configuration
Test components: Use individual test commands like kgit status or kospex system-status
Check environment: Verify environment variables and directory permissions

For additional support, check the GitHub Issues or create a new issue with:

Operating system details
Kospex version (kospex --version)
Full error messages and logs
Steps to reproduce the issue