---
sidebar_label: "Troubleshooting"
sidebar_custom_props:
  section: "Templates"
  section_position: 1
---

{/*

Troubleshooting pages help users diagnose and resolve common issues. Organize by error type 
or symptom. Provide clear problem descriptions, root causes, and step-by-step solutions. 
Include command examples and expected outputs for verification.

*/}

# Troubleshooting Template

Solutions to common issues and error messages you may encounter.

## Installation Issues

### Command Not Found After Installation

**Problem:** Running `example-tool` returns "command not found" error.

**Cause:** The installation directory is not in your system's PATH.

**Solution:**

```bash
# Check if the tool is installed
which example-tool

# Add to PATH (temporary)
export PATH="$PATH:/usr/local/bin"

# Add to PATH (permanent - add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrc
source ~/.bashrc
```

**Verify:**

```bash
example-tool --version
```

### Permission Denied

**Problem:** Installation fails with "permission denied" error.

**Cause:** Insufficient permissions to write to installation directory.

**Solution:**

```bash
# On Linux/macOS, use sudo
sudo example-tool install

# Or install to user directory
example-tool install --user

# Make binary executable
chmod +x /usr/local/bin/example-tool
```

### SSL Certificate Verification Failed

**Problem:** Download fails with SSL certificate errors.

**Cause:** Corporate proxy, outdated certificates, or network security settings.

**Solution:**

```bash
# Update CA certificates (Ubuntu/Debian)
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

# As last resort (not recommended for production)
curl -k https://example.com/install.sh | bash
```

## Configuration Issues

### Configuration File Not Found

**Problem:** Tool reports "configuration file not found" error.

**Cause:** No config file exists in the expected locations.

**Solution:**

```bash
# Create default configuration
example-tool init

# Or create manually
mkdir -p ~/.config/example-tool
cat > ~/.config/example-tool/config.yml << EOF
app:
  name: my-app
  environment: development
EOF
```

**Verify:**

```bash
example-tool config show
```

### Invalid Configuration Syntax

**Problem:** Error message: "Invalid YAML syntax" or "Failed to parse configuration".

**Cause:** Syntax errors in the configuration file.

**Solution:**

```bash
# Validate configuration
example-tool config validate

# Check for common issues:
# - Incorrect indentation (use spaces, not tabs)
# - Missing colons after keys
# - Unquoted special characters

# View line-by-line
cat -n ~/.config/example-tool/config.yml
```

### Environment Variables Not Working

**Problem:** Environment variables are not overriding configuration values.

**Cause:** Incorrect variable names or not exported.

**Solution:**

```bash
# Check current environment variables
env | grep EXAMPLE

# Export variables correctly
export EXAMPLE_API_KEY="your-key"
export EXAMPLE_ENDPOINT="https://api.example.com"

# Verify they're loaded
example-tool config show --effective
```

## Common Error Messages

### Error: "Port already in use"

**Solution:**

```bash
# Find process using the port
lsof -ti:8080

# Kill the process
kill -9 $(lsof -ti:8080)

# Or use a different port
example-tool start --port 9000
```

### Error: "Disk quota exceeded"

**Solution:**

```bash
# Check disk usage
df -h

# Clean up cache
example-tool cache clear

# Remove old logs
rm -rf ~/.config/example-tool/logs/*.log
```

### Error: "Unable to lock file"

**Solution:**

```bash
# Find and remove stale lock files
find ~/.config/example-tool -name "*.lock" -delete

# Or wait for existing operation to complete
ps aux | grep example-tool
```

## Debugging

### Enable Verbose Logging

```bash
# Enable debug output
example-tool --verbose command

# Or set log level
export LOG_LEVEL=debug
example-tool command

# Save logs to file
example-tool --verbose command 2>&1 | tee debug.log
```

### Run Diagnostics

```bash
# Run health check
example-tool doctor

# Verify system requirements
example-tool check-system

# Test connectivity
example-tool test connection
```

### Inspect Network Traffic

```bash
# Enable HTTP debugging
export DEBUG=http
example-tool command

# Use curl to test API directly
curl -v -H "Authorization: Bearer YOUR_KEY" \
  https://api.example.com/v1/resource
```

## Getting Additional Help

If these solutions don't resolve your issue:

1. **Check logs:** `~/.config/example-tool/logs/`
2. **Search issues:** [GitHub Issues](https://github.com/example/tool/issues)
3. **Ask the community:** [Forum](https://forum.example.com)
4. **Contact support:** support@example.com

When reporting issues, include:
- Tool version (`example-tool --version`)
- Operating system and version
- Complete error message
- Steps to reproduce
- Relevant configuration (remove sensitive data)

:::tip Quick Diagnostics
Run `example-tool doctor` to automatically check for common configuration and environment issues.
:::

:::warning Before Reinstalling
Try `example-tool repair` to fix common issues without losing your configuration.
:::