> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kafkalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for KafkaCode

## Installation Issues

### Command Not Found

**Problem:** `kafkacode: command not found`

**Solutions:**

<AccordionGroup>
  <Accordion title="Solution 1: Use npx">
    ```bash theme={null}
    npx kafkacode scan ./src
    ```
  </Accordion>

  <Accordion title="Solution 2: Check Installation">
    ```bash theme={null}
    npm list -g kafkacode
    npm install -g kafkacode
    ```
  </Accordion>

  <Accordion title="Solution 3: Fix PATH">
    ```bash theme={null}
    # Add npm global bin to PATH
    export PATH="$(npm config get prefix)/bin:$PATH"

    # Make permanent (bash)
    echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc

    # Make permanent (zsh)
    echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Accordion>
</AccordionGroup>

### Permission Errors

**Problem:** `EACCES: permission denied`

**Solutions:**

<AccordionGroup>
  <Accordion title="Solution 1: Use npx (Recommended)">
    ```bash theme={null}
    npx kafkacode scan ./src
    ```
  </Accordion>

  <Accordion title="Solution 2: Fix npm Permissions">
    ```bash theme={null}
    mkdir ~/.npm-global
    npm config set prefix '~/.npm-global'
    echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
    source ~/.bashrc
    npm install -g kafkacode
    ```
  </Accordion>

  <Accordion title="Solution 3: Use nvm">
    ```bash theme={null}
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
    nvm install node
    npm install -g kafkacode
    ```
  </Accordion>
</AccordionGroup>

## Scan Issues

### No Files Found

**Problem:** "No source code files found to analyze"

**Check:**

1. Verify directory exists: `ls -la /path/to/directory`
2. Check for supported file types: `.py`, `.js`, `.ts`, `.java`, `.go`, `.rb`, `.php`
3. Check if files are gitignored
4. Use verbose mode: `kafkacode scan ./src --verbose`

### Slow Performance

**Problem:** Scan takes too long

**Solutions:**

<AccordionGroup>
  <Accordion title="Scan Specific Directories">
    ```bash theme={null}
    # Instead of scanning everything
    kafkacode scan ./src

    # Not
    kafkacode scan .
    ```
  </Accordion>

  <Accordion title="Add to .gitignore">
    ```gitignore theme={null}
    test-fixtures/
    large-data/
    generated/
    ```
  </Accordion>

  <Accordion title="Exclude Large Directories">
    ```javascript theme={null}
    const scanner = new FileScanner('./src');
    scanner.ignoreDirs.add('test-data');
    scanner.ignoreDirs.add('fixtures');
    ```
  </Accordion>
</AccordionGroup>

## CI/CD Issues

### Fails in CI but Works Locally

**Check:**

1. Node.js version: Requires Node 14+
2. File paths: Use absolute or relative paths consistently
3. Exit codes: Check if CI expects specific exit codes
4. Verbose mode in CI for debugging

### GitHub Actions Timeout

```yaml theme={null}
# Increase timeout
- name: Privacy Scan
  run: kafkacode scan ./src --verbose
  timeout-minutes: 10
```

## False Positives

### Test Data Flagged

**Solution:** Add comments or use clear naming:

```javascript theme={null}
// Before (flagged)
const apiKey = "test-key-123";

// After (clearer)
const TEST_API_KEY = "fake-key-for-testing-only";
// OR
const apiKey = "REPLACE_WITH_YOUR_API_KEY";
```

### Environment Variables Flagged

This shouldn't happen, but if it does:

```javascript theme={null}
// This should NOT be flagged
const apiKey = process.env.API_KEY;

// If it is, please report the issue
```

## Getting Help

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/nikhil-kapu/KafkacodeFnpm/issues">
    Report bugs or request features
  </Card>

  <Card title="Documentation" icon="book" href="/introduction">
    Review the docs
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:contact@kafkalabs.com">
    Contact KafkaLabs support
  </Card>

  <Card title="Community" icon="users" href="https://kafkalabs.com">
    Join the community
  </Card>
</CardGroup>