Troubleshooting Guide

This guide helps you diagnose and resolve common issues with Kollect discovery and platform connections.

General Troubleshooting

Check Platform Connections

First, verify which platforms kollect can connect to:

# Check connection status
curl http://localhost:8080/api/check-credentials

Web Interface Not Loading

If the web interface isn't accessible:

# Verify kollect is running on port 8080
lsof -i :8080

# Or check with netstat
netstat -tulpn | grep :8080

No Data Showing

If kollect starts but shows no data:

Ensure you specified an inventory type: ./kollect --inventory all
Check that your cloud CLI tools are configured and authenticated
Look for error messages in the terminal output

Platform Connection Issues

AWS Connection Problems

AWS shows "Not Connected" in web interface

Troubleshooting Steps:

Test AWS CLI access:
```
aws sts get-caller-identity
```
Verify AWS credentials are configured:
```
ls ~/.aws/
cat ~/.aws/credentials
```
Try running kollect with AWS inventory:
```
./kollect --inventory aws
```

Required AWS Permissions

Kollect needs read-only permissions for discovery:

# Minimum required permissions
ec2:Describe*
s3:ListAllMyBuckets
s3:GetBucket*
rds:Describe*
dynamodb:ListTables
dynamodb:DescribeTable
efs:DescribeFileSystems

Azure Connection Problems

Azure shows "Not Connected" in web interface

Troubleshooting Steps:

Test Azure CLI access:
```
az account show
```
If not logged in:
```
az login
```
Try running kollect with Azure inventory:
```
./kollect --inventory azure
```

Google Cloud Connection Problems

GCP shows "Not Connected" in web interface

Troubleshooting Steps:

Test gcloud access:

gcloud auth list
gcloud config get-value project

Set application default credentials:
```
gcloud auth application-default login
```
Try running kollect with GCP inventory:
```
./kollect --inventory gcp
```

Kubernetes Connection Problems

Kubernetes shows "Not Connected" in web interface

Troubleshooting Steps:

Test kubectl access:
```
kubectl cluster-info
kubectl get nodes
```

Check kubeconfig file:

ls ~/.kube/config
kubectl config get-contexts

Try with specific kubeconfig:

./kollect --inventory kubernetes --kubeconfig ~/.kube/config

Docker Connection Problems

Docker shows "Not Connected" in web interface

Troubleshooting Steps:

Test Docker daemon access:
```
docker info
docker ps
```
Check Docker daemon is running:
```
systemctl status docker
```

Try with custom Docker host:

./kollect --inventory docker --docker-host unix:///var/run/docker.sock

VMware vSphere Connection Problems

vSphere shows "Not Connected" in web interface

Troubleshooting Steps:

Test vCenter connectivity:

ping vcenter.example.com
telnet vcenter.example.com 443

Try connecting with kollect:

./kollect --inventory vsphere \
  --vsphere-server vcenter.example.com \
  --vsphere-username readonly@vsphere.local \
  --vsphere-password yourpassword \
  --vsphere-insecure

Use environment variables for credentials:

export VSPHERE_SERVER="vcenter.example.com"
export VSPHERE_USERNAME="readonly@vsphere.local"
export VSPHERE_PASSWORD="yourpassword"
export VSPHERE_INSECURE="true"
./kollect --inventory vsphere

Terraform Connection Problems

Terraform shows "Not Connected" in web interface

Troubleshooting Steps:

Check Terraform CLI is installed:
```
terraform version
```

For local state file:

ls -la terraform.tfstate
./kollect --inventory terraform --terraform-state ./terraform.tfstate

For remote S3 backend:

./kollect --inventory terraform \
  --terraform-s3 mybucket/terraform.tfstate \
  --terraform-s3-region us-east-1

Vault Connection Problems

Vault shows "Not Connected" in web interface

Troubleshooting Steps:

Test Vault connectivity:

curl -k https://vault.example.com:8200/v1/sys/health

Try with environment variables:

export VAULT_ADDR="https://vault.example.com:8200"
export VAULT_TOKEN="s.abc123..."
./kollect --inventory vault

Or with command-line flags:

./kollect --inventory vault \
  --vault-addr https://vault.example.com:8200 \
  --vault-token s.abc123...

Common Issues

No Data Displayed

Web interface loads but shows no data

Solutions:

Make sure you specified an inventory type:
```
./kollect --inventory all
```
Check the terminal output for error messages

Verify platform connections:

curl http://localhost:8080/api/check-credentials

Try importing existing data:
```
./kollect --browser
```

Port 8080 Already in Use

Error: "bind: address already in use"

Solutions:

Find what's using port 8080:

lsof -i :8080
netstat -tulpn | grep :8080

Kill the process using the port:
```
kill -9 PID_NUMBER
```
Note: Kollect's port cannot be changed - it's hardcoded to 8080

Network and Connectivity Issues

Connection Timeouts

Issue: Discovery operations timing out

Possible causes:

Network connectivity issues
Firewall blocking API calls
Large number of resources causing timeouts

Solutions:

Increase timeout values:
```
./kollect -timeout 10m
```
Reduce concurrent scans:
```
./kollect -concurrent 2
```

Test connectivity to cloud APIs:

# Test AWS connectivity
curl -I https://ec2.amazonaws.com

# Test Azure connectivity  
curl -I https://management.azure.com

# Test GCP connectivity
curl -I https://compute.googleapis.com

Proxy Configuration

If you're behind a corporate proxy:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

Performance Issues

Slow Discovery

Optimizing Discovery Performance

Increase concurrent operations:
```
export KOLLECT_CONCURRENT_SCANS=10
```

Limit regions/projects:

export KOLLECT_AWS_REGIONS="us-east-1,us-west-2"
export KOLLECT_GCP_PROJECTS="project1,project2"

Filter resource types:

export KOLLECT_AWS_SERVICES="ec2,s3,rds"

High Memory Usage

For large infrastructures, Kollect may consume significant memory:

Process smaller regions/projects separately
Enable result streaming (if available)
Increase system memory or use a larger instance

Docker Issues

Docker Socket Permission Denied

Error: "permission denied while connecting to Docker daemon socket"

Solution:

Add user to docker group:

sudo usermod -aG docker $USER
# Logout and login again

Or run with sudo:
```
sudo ./kollect
```

Kubernetes Issues

Kubeconfig Not Found

Error: "kubeconfig not found"

Solution:

Verify kubeconfig exists:
```
ls -la ~/.kube/config
```
Test kubectl access:
```
kubectl cluster-info
```

Set custom kubeconfig path:

export KUBECONFIG=/path/to/your/kubeconfig

Web Interface Issues

Web Interface Not Loading

Issue: Cannot access http://localhost:8080

Troubleshooting steps:

Check if Kollect is running:
```
ps aux | grep kollect
```
Verify port is available:
```
netstat -tulpn | grep :8080
```
Try different port:
```
./kollect -port 9090
```
Check firewall settings

API Returning Empty Data

Possible causes:

Discovery still in progress
Authentication issues preventing data collection
No resources found in configured regions/projects
Filters excluding all resources

Check discovery status:

curl http://localhost:8080/api/status

Common Configuration Mistakes

Wrong Region Configuration

# Wrong - using unavailable region
export KOLLECT_AWS_REGIONS="us-east-3"

# Correct - using valid region
export KOLLECT_AWS_REGIONS="us-east-1"

Incorrect Environment Variables

# Check current environment variables
env | grep -E "(AWS|AZURE|GOOGLE|KOLLECT)"

# Clear conflicting variables if needed
unset AZURE_CLIENT_ID

Getting Help

Enable Debug Mode

# Run with maximum logging
export KOLLECT_LOG_LEVEL=debug
./kollect -verbose

Collect Diagnostic Information

# System information
uname -a
./kollect -version

# Network connectivity
curl -I https://ec2.amazonaws.com
curl -I https://management.azure.com

# Environment variables
env | grep -E "(AWS|AZURE|GOOGLE)" | sed 's/=.*/=***REDACTED***/'

Community Support

GitHub Issues - Report bugs and request features
GitHub Discussions - Ask questions and share solutions
Check existing documentation and wiki

When reporting issues:

Include Kollect version and OS information
Provide error messages and logs
Describe steps to reproduce the issue
Remove sensitive information (credentials, IPs, etc.)

FAQ

Q: Why is discovery taking so long?

A: Large infrastructures with many resources can take time to scan. Try limiting regions/projects, increasing concurrent scans, or filtering resource types.

Q: Can I run Kollect in read-only mode?

A: Yes, Kollect only performs read operations. Ensure your credentials have only read permissions for security.

Q: Does Kollect store my data?

A: Kollect stores discovery results in memory during operation. Data is not persisted unless you explicitly export it.

Q: Can I run multiple instances of Kollect?

A: Yes, but use different ports and be mindful of API rate limits from cloud providers.