Troubleshooting

Installation Issues

Command Not Found

Problem: kafkacode: command not found Solutions:

Solution 1: Use npx

npx kafkacode scan ./src

Solution 2: Check Installation

npm list -g kafkacode
npm install -g kafkacode

Solution 3: Fix PATH

# 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

Permission Errors

Problem: EACCES: permission denied Solutions:

Solution 1: Use npx (Recommended)

npx kafkacode scan ./src

Solution 2: Fix npm Permissions

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g kafkacode

Solution 3: Use nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node
npm install -g kafkacode

Scan Issues

No Files Found

Problem: “No source code files found to analyze” Check:

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

Slow Performance

Problem: Scan takes too long Solutions:

Scan Specific Directories

# Instead of scanning everything
kafkacode scan ./src

# Not
kafkacode scan .

Add to .gitignore

test-fixtures/
large-data/
generated/

Exclude Large Directories

const scanner = new FileScanner('./src');
scanner.ignoreDirs.add('test-data');
scanner.ignoreDirs.add('fixtures');

CI/CD Issues

Fails in CI but Works Locally

Check:

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

GitHub Actions Timeout

# 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:

// 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:

// This should NOT be flagged
const apiKey = process.env.API_KEY;

// If it is, please report the issue

Getting Help

GitHub Issues

Report bugs or request features

Documentation

Review the docs

Email Support

Contact KafkaLabs support

Community

Join the community

Get Started

Core Concepts

Usage Guide

Advanced

Installation Issues

Command Not Found

Permission Errors

Scan Issues

No Files Found

Slow Performance

CI/CD Issues

Fails in CI but Works Locally

GitHub Actions Timeout

False Positives

Test Data Flagged

Environment Variables Flagged

Getting Help

GitHub Issues

Documentation

Email Support

Community

​Installation Issues

​Command Not Found

​Permission Errors

​Scan Issues

​No Files Found

​Slow Performance

​CI/CD Issues

​Fails in CI but Works Locally

​GitHub Actions Timeout

​False Positives

​Test Data Flagged

​Environment Variables Flagged

​Getting Help

GitHub Issues

Documentation

Email Support

Community

Installation Issues

Command Not Found

Permission Errors

Scan Issues

No Files Found

Slow Performance

CI/CD Issues

Fails in CI but Works Locally

GitHub Actions Timeout

False Positives

Test Data Flagged

Environment Variables Flagged

Getting Help