License Compliance Checker - Troubleshooting Guide¶

Table of Contents¶

Installation Issues
Scanning Issues
License Resolution Issues
Policy Issues
API and Server Issues
Dashboard Issues
Docker Issues
Performance Issues
Database Issues
Getting Help

Installation Issues¶

pip install fails with "No matching distribution found"¶

Symptoms:

ERROR: Could not find a version that satisfies the requirement lcc

Causes & Solutions:

Wrong package name: The package is license-compliance-checker, not lcc

# Correct
pip install license-compliance-checker

# Incorrect
pip install lcc

Python version too old: LCC requires Python 3.9+

# Check Python version
python --version

# Upgrade Python if needed
# On macOS with Homebrew:
brew install python@3.11

# On Ubuntu:
sudo apt install python3.11

pip is outdated: Upgrade pip

pip install --upgrade pip setuptools wheel

ModuleNotFoundError after installation¶

Symptoms:

ModuleNotFoundError: No module named 'lcc'

Causes & Solutions:

Multiple Python environments: Installed in wrong environment

# Check which Python is being used
which python
which pip

# Use pip with the same Python
python -m pip install license-compliance-checker

# Or use venv
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install license-compliance-checker

Editable install issue: Reinstall

pip uninstall license-compliance-checker
pip install license-compliance-checker

"Command 'lcc' not found"¶

Symptoms:

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

Causes & Solutions:

PATH not configured: Add pip bin directory to PATH

# Find where pip installs binaries
python -m site --user-base

# Add to PATH (in ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

# Reload shell
source ~/.bashrc

Use as module: Run as Python module instead
```
python -m lcc.cli.main --version
```

Scanning Issues¶

"No detectors found components"¶

Symptoms:

INFO: Scan completed in 0.1s
INFO: Found 0 components

Causes & Solutions:

Wrong directory: Not in project root

# Check directory contents
ls -la

# Look for package manifests
find . -name "package.json" -o -name "requirements.txt" -o -name "go.mod"

# Scan correct directory
lcc scan /path/to/project/root

Unsupported language: LCC supports Python, JavaScript, Go, Rust, Java, Ruby, .NET
```
# Check if your language is supported
lcc --help
```
Manifest file in subdirectory: Use recursive option
```
lcc scan . --recursive
```

Scan is very slow¶

Symptoms: - Scan takes > 5 minutes - High CPU or memory usage

Causes & Solutions:

Large project with many files: Exclude unnecessary directories

lcc scan . --exclude "node_modules" --exclude "vendor" --exclude ".git"

GitHub API rate limiting: Use GitHub token

# Set GitHub token
export GITHUB_TOKEN="ghp_your_token_here"

# Or in config.yaml
github:
  token: ghp_your_token_here

Network issues: Use cache

# Enable cache (default)
lcc scan . --cache-ttl 86400  # 24 hours

Too many resolvers: Disable unused resolvers

# config.yaml
resolvers:
  - registry  # Fast
  - clearlydefined  # Medium
  # - github  # Slow, disable if not needed

"Permission denied" when scanning¶

Symptoms:

ERROR: Permission denied: /path/to/file

Causes & Solutions:

Insufficient file permissions: Run with appropriate permissions

# Check permissions
ls -la /path/to/file

# Fix permissions
chmod +r /path/to/file

# Or run as root (not recommended)
sudo lcc scan /path

SELinux blocking access: Temporarily disable or configure

# Check SELinux status
getenforce

# Temporarily disable (for testing only)
sudo setenforce 0

License Resolution Issues¶

Many "UNKNOWN" licenses¶

Symptoms: - Report shows many components with "UNKNOWN" license - Policy violations due to unknown licenses

Causes & Solutions:

Package not in registries: Add custom metadata

# overrides.yaml
overrides:
  my-package:
    license: MIT
    reason: "Verified from upstream GitHub repo"

Network issues: Check connectivity

# Test registry access
curl https://pypi.org/pypi/requests/json
curl https://registry.npmjs.org/express

# Test GitHub API
curl https://api.github.com/rate_limit

GitHub rate limiting: Set GitHub token

export GITHUB_TOKEN="ghp_your_token_here"

Custom packages: Use local resolution

# Scan with local LICENSE files
lcc scan . --resolvers filesystem

Incorrect license detected¶

Symptoms: - License doesn't match upstream source - Dual-license not properly detected

Causes & Solutions:

Registry metadata is wrong: Use override

# overrides.yaml
overrides:
  package-name:
    license: "MIT OR Apache-2.0"
    reason: "Registry metadata incorrect, verified from source"

SPDX expression parsing issue: Simplify or override

overrides:
  complex-package:
    license: Apache-2.0  # Choose preferred license

Custom/proprietary license: Add to policy

# policy.yaml
contexts:
  production:
    allow:
      - Proprietary-CompanyName

AI/ML model license not detected¶

Symptoms: - Hugging Face models show "UNKNOWN" - Dataset licenses not recognized

Causes & Solutions:

Missing model card: Add metadata

overrides:
  bert-base-uncased:
    license: Apache-2.0
    type: huggingface

Custom AI license: Add to policy

contexts:
  research:
    allow:
      - llama-2
      - openrail-m
      - deepmind-gemma

Hugging Face API issues: Check connectivity

# Test Hugging Face API
curl https://huggingface.co/api/models/bert-base-uncased

Policy Issues¶

Policy file not found¶

Symptoms:

ERROR: Policy 'my-policy' not found

Causes & Solutions:

Wrong policy directory: Check policy location

# Default location
ls ~/.lcc/policies/

# Check config
lcc config show | grep policy_dir

# Set custom location
export LCC_POLICY_DIR=/path/to/policies

Wrong file extension: Use .yaml or .yml

# Correct
my-policy.yaml
my-policy.yml

# Incorrect
my-policy.json
my-policy.txt

File permissions: Check read permissions

ls -la ~/.lcc/policies/
chmod +r ~/.lcc/policies/my-policy.yaml

Policy validation fails¶

Symptoms:

ERROR: Invalid policy: ...

Causes & Solutions:

YAML syntax error: Check YAML formatting

# Validate YAML
lcc policy validate my-policy

# Check for tabs (YAML requires spaces)
cat -A my-policy.yaml | grep "\t"

Missing required fields: Add required fields

name: my-policy
version: "1.0"
contexts:
  production:
    allow: []
    deny: []
    review: []

Invalid license identifier: Check SPDX identifiers

# Correct
allow:
  - Apache-2.0
  - GPL-3.0

# Incorrect
allow:
  - Apache 2.0  # No spaces
  - GPLv3       # Use official identifier

Unexpected policy results¶

Symptoms: - Allowed licenses are flagged - Denied licenses pass

Causes & Solutions:

Wrong context: Specify correct context

# Check which context is being used
lcc scan . --policy my-policy --context production --dry-run

Wildcard not matching: Check pattern

# Specific
allow:
  - GPL-2.0
  - GPL-3.0

# Wildcard (matches both)
allow:
  - GPL-*

Dual-license preference: Check preference setting

contexts:
  production:
    dual_license_preference: most_permissive  # or avoid_copyleft

API and Server Issues¶

"Connection refused" when accessing API¶

Symptoms:

curl: (7) Failed to connect to localhost port 8000: Connection refused

Causes & Solutions:

Server not running: Start server

# Check if server is running
ps aux | grep "lcc server"

# Start server
lcc server

# Or with Docker
docker-compose up -d

Wrong port: Check configured port

# Default is 8000
curl http://localhost:8000/health

# If using custom port
lcc server --port 8080
curl http://localhost:8080/health

Firewall blocking: Check firewall

# Check if port is open
netstat -tuln | grep 8000

# On macOS
lsof -i :8000

Authentication fails¶

Symptoms:

{"detail": "Could not validate credentials"}

Causes & Solutions:

No user exists: Create user first

lcc auth create-user admin password123 --role admin

Wrong credentials: Verify username/password

# Login via CLI to test
lcc auth login admin

Token expired: Get new token

# Access tokens expire after 24 hours
curl -X POST http://localhost:8000/auth/login \
  -d "username=admin&password=password123"

Wrong Authorization header: Check header format

# Correct
curl -H "Authorization: Bearer eyJ..." http://localhost:8000/scans

# Incorrect
curl -H "Authorization: eyJ..." http://localhost:8000/scans  # Missing "Bearer"

Rate limit exceeded¶

Symptoms:

{"detail": "Rate limit exceeded: 100 per 1 minute"}

Causes & Solutions:

Too many requests: Wait and retry

# Wait for rate limit to reset (check Retry-After header)
sleep 60

Increase rate limit: Configure in code (self-hosted only)

# In server.py
@limiter.limit("1000/minute")  # Increase limit

Use caching: Cache responses client-side

Dashboard Issues¶

Dashboard shows "Failed to fetch"¶

Symptoms: - Dashboard loads but shows errors - API requests fail

Causes & Solutions:

API not running: Start API server
```
docker-compose up -d
```

Wrong API URL: Check environment variables

# In dashboard/.env.local
NEXT_PUBLIC_API_URL=http://localhost:8000

CORS issue: Configure CORS

# Set allowed origins
export LCC_ALLOWED_ORIGINS="http://localhost:3000,http://localhost:3001"

Dashboard won't start¶

Symptoms:

Error: Cannot find module 'next'

Causes & Solutions:

Dependencies not installed: Install dependencies
```
cd dashboard
npm install
```

Port already in use: Change port or kill process

# Check what's using port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
PORT=3001 npm run dev

Node version incompatible: Use Node 18+

# Check Node version
node --version

# Upgrade Node
nvm install 18
nvm use 18

Symptoms: - Login form doesn't work - "Invalid credentials" error

Causes & Solutions:

No user exists: Create user via CLI

lcc auth create-user admin password123 --role admin --email admin@company.com

API not accessible: Check API connectivity
```
curl http://localhost:8000/health
```
Browser cache: Clear cache and cookies

Docker Issues¶

"docker-compose: command not found"¶

Symptoms:

bash: docker-compose: command not found

Causes & Solutions:

Docker Compose not installed: Install Docker Compose

# On Docker Desktop, Compose v2 is included
# Use 'docker compose' instead of 'docker-compose'
docker compose up -d

# Or install standalone
pip install docker-compose

"port is already allocated"¶

Symptoms:

ERROR: for api  Cannot start service api: driver failed programming external connectivity:
Bind for 0.0.0.0:8000 failed: port is already allocated

Causes & Solutions:

Port in use: Change port or stop conflicting service

# Check what's using port
lsof -i :8000

# Kill process
kill -9 <PID>

# Or change port in docker-compose.yml
ports:
  - "8001:8000"  # Map to 8001 instead

Previous container still running: Stop old containers
```
docker-compose down
docker-compose up -d
```

"Cannot connect to Docker daemon"¶

Symptoms:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Causes & Solutions:

Docker not running: Start Docker

# On macOS/Windows: Start Docker Desktop

# On Linux
sudo systemctl start docker

Permission denied: Add user to docker group

sudo usermod -aG docker $USER
newgrp docker

Container exits immediately¶

Symptoms:

$ docker-compose ps
NAME    STATE     PORTS
api     Exit 1

Causes & Solutions:

Check logs: View container logs

docker-compose logs api
docker logs <container_id>

Database migration issue: Reset database

docker-compose down -v  # Remove volumes
docker-compose up -d

Configuration error: Check environment variables

# Verify .env file
cat .env

# Check if variables are set
docker-compose config

Performance Issues¶

Slow scan on large projects¶

Solutions:

Exclude large directories:

lcc scan . --exclude "node_modules" --exclude "vendor" --exclude ".venv"

Increase cache TTL:

# config.yaml
cache:
  ttl: 604800  # 7 days

Use faster resolvers only:

resolvers:
  - registry  # Fast
  - clearlydefined  # Medium
  # Disable slow resolvers

Disable unnecessary detectors:

detectors:
  - npm
  - pypi
  # Disable detectors for languages you don't use

High memory usage¶

Solutions:

Scan smaller subsets:

# Scan specific directories
lcc scan ./src
lcc scan ./backend

Limit concurrent operations:

# config.yaml
max_concurrent_resolvers: 5  # Default is 10

Use Docker with memory limits:

# docker-compose.yml
services:
  api:
    mem_limit: 2g

Database Issues¶

Database locked error¶

Symptoms:

sqlite3.OperationalError: database is locked

Causes & Solutions:

Multiple instances: Stop other LCC processes
```
ps aux | grep lcc
kill <PID>
```

Database corruption: Recreate database

# Backup
cp ~/.lcc/lcc.db ~/.lcc/lcc.db.backup

# Remove and recreate
rm ~/.lcc/lcc.db
lcc server  # Will recreate on start

Can't access database¶

Symptoms:

ERROR: Cannot open database

Causes & Solutions:

Permission denied: Fix permissions

chmod 644 ~/.lcc/lcc.db
chmod 755 ~/.lcc/

Disk full: Free up space

df -h
# Clean up old scans
lcc scans clean --older-than 30d

Getting Help¶

Diagnostic Information¶

When asking for help, provide:

# System information
lcc --version
python --version
pip list | grep license

# Configuration
lcc config show

# Last scan logs
lcc scan . --verbose

# API logs
docker-compose logs api --tail 100

# Dashboard logs
docker-compose logs dashboard --tail 100

Verbose Logging¶

Enable detailed logging:

# CLI
lcc scan . --verbose

# Set log level via environment
export LCC_LOG_LEVEL=DEBUG
lcc scan .

# API server
lcc server --log-level DEBUG

Common Log Locations¶

# CLI logs
~/.lcc/logs/lcc.log

# Docker logs
docker-compose logs -f api
docker-compose logs -f dashboard

# System logs (Linux)
journalctl -u lcc

# System logs (macOS)
tail -f /var/log/system.log | grep lcc

Support Channels¶

Documentation: https://docs.lcc.dev
GitHub Issues: https://github.com/your-org/lcc/issues
GitHub Discussions: https://github.com/your-org/lcc/discussions
Email: support@lcc.dev

Before Filing an Issue¶

Check existing issues: https://github.com/your-org/lcc/issues
Search documentation
Try the latest version
Collect diagnostic information
Create minimal reproducible example

Issue Template¶

**Environment**:
- LCC version: [run `lcc --version`]
- Python version: [run `python --version`]
- OS: [e.g., Ubuntu 22.04, macOS 13.5]
- Installation method: [pip, Docker, source]

**Description**:
[Clear description of the issue]

**Steps to Reproduce**:
1.
2.
3.

**Expected behavior**:
[What you expected to happen]

**Actual behavior**:
[What actually happened]

**Logs**:

[Paste relevant logs with --verbose flag]

**Additional context**:
[Any other relevant information]

Quick Reference¶

Health Checks¶

# Check if LCC is working
lcc --version

# Check if API is running
curl http://localhost:8000/health

# Check if Dashboard is running
curl http://localhost:3000

# Check database
sqlite3 ~/.lcc/lcc.db "SELECT COUNT(*) FROM scans;"

Reset Everything¶

# WARNING: This deletes all data

# Stop services
docker-compose down -v

# Remove database and cache
rm -rf ~/.lcc/

# Restart
docker-compose up -d

# Recreate admin user
lcc auth create-user admin password123 --role admin

Performance Tuning¶

# config.yaml - Fast configuration
cache:
  enabled: true
  ttl: 604800  # 7 days

resolvers:
  - registry  # Fastest
  - clearlydefined

detection:
  max_depth: 5
  timeout: 60

max_concurrent_resolvers: 5

For additional help, see FAQ.md or contact support@lcc.dev

License Compliance Checker - Troubleshooting Guide¶

Table of Contents¶

Installation Issues¶

pip install fails with "No matching distribution found"¶

ModuleNotFoundError after installation¶

"Command 'lcc' not found"¶

Scanning Issues¶

"No detectors found components"¶

Scan is very slow¶

"Permission denied" when scanning¶

License Resolution Issues¶

Many "UNKNOWN" licenses¶

Incorrect license detected¶

AI/ML model license not detected¶

Policy Issues¶

Policy file not found¶

Policy validation fails¶

Unexpected policy results¶

API and Server Issues¶

"Connection refused" when accessing API¶

Authentication fails¶

Rate limit exceeded¶

Dashboard Issues¶

Dashboard shows "Failed to fetch"¶

Dashboard won't start¶

Can't login to dashboard¶

Docker Issues¶

"docker-compose: command not found"¶

"port is already allocated"¶

"Cannot connect to Docker daemon"¶

Container exits immediately¶

Performance Issues¶

Slow scan on large projects¶

High memory usage¶

Database Issues¶

Database locked error¶

Can't access database¶

Getting Help¶

Diagnostic Information¶

Verbose Logging¶

Common Log Locations¶

Support Channels¶

Before Filing an Issue¶

Issue Template¶

Quick Reference¶

Health Checks¶

Reset Everything¶

Performance Tuning¶