Common Issues

Solutions to frequently encountered problems with NikCLI

Quick Diagnostics

If you’re experiencing issues with NikCLI, start with these diagnostic commands:

System Check

nikcli --version
nikcli config list
nikcli debug

Connection Test

nikcli test connection
nikcli models
nikcli agents

Installation and Setup Issues

Node.js Version Conflicts

Error: Node.js version 18+ required

Problem: NikCLI requires Node.js 18 or higher

Symptoms:

Error: NikCLI requires Node.js version 18 or higher. 
Current version: v16.14.0

Solutions:

Using NVM (Recommended)

# Install Node Version Manager
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal or source profile
source ~/.bashrc

# Install and use Node.js 18
nvm install 18
nvm use 18
nvm alias default 18

# Verify installation
node --version  # Should show v18.x.x

Permission Denied During Installation

Problem: Insufficient permissions for global npm installation

Symptoms:

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Solutions:

Configure npm Directory (Recommended)

# Create a directory for global installations
mkdir ~/.npm-global

# Configure npm to use the new directory
npm config set prefix '~/.npm-global'

# Add to your shell profile
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Install NikCLI
npm install -g @cadcamfun/nikcli

Command Not Found After Installation

Problem: NikCLI installed but not found in PATH

Symptoms:

bash: nikcli: command not found

Solutions:

1. Check Installation Location:

npm list -g @cadcamfun/nikcli
npm config get prefix

2. Add to PATH:

# Find npm bin directory
npm bin -g

# Add to PATH (adjust path as needed)
echo 'export PATH=$(npm bin -g):$PATH' >> ~/.bashrc
source ~/.bashrc

3. Verify PATH Configuration:

echo $PATH
which nikcli

API Key and Authentication Issues

API Key Configuration Problems

API Key Not Detected

Problem: NikCLI cannot find your API key

Symptoms:

Error: No API key configured. Please set your API key.
Available providers: anthropic, openai, google

Solutions:

Environment Variables

# Set API key in environment
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# Make it persistent
echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc

# Verify it's set
echo $ANTHROPIC_API_KEY

Invalid API Key Error

Problem: API key is invalid or has insufficient permissions

Symptoms:

Error: Invalid API key or insufficient permissions
Status: 401 Unauthorized

Solutions:

1. Verify API Key:

# Check current configuration
nikcli debug

# Test specific provider
nikcli test connection anthropic

2. Check API Key Format:

• Anthropic: Should start with sk-ant-api03-
• OpenAI: Should start with sk-
• Google: Should be a string without specific prefix

3. Verify Permissions:

• Ensure API key has required scopes
• Check usage limits and quotas
• Verify account status

4. Generate New Key:

• Go to your provider’s console
• Generate a new API key
• Update NikCLI configuration

Rate Limiting Issues

Problem: API requests are being rate limited

Symptoms:

Error: Rate limit exceeded
Status: 429 Too Many Requests
Retry after: 60 seconds

Solutions:

1. Check Usage:

nikcli stats

2. Reduce Request Frequency:

# Set longer delays between requests
nikcli config set request-delay 2000

# Reduce token limits
nikcli config set token-limit 50000

3. Use Alternative Provider:

# Switch to different provider
nikcli model openai:gpt-4

4. Upgrade Plan:

• Consider upgrading your API plan
• Check provider pricing and limits

Project and Context Issues

Workspace Detection Problems

Project Type Not Detected

Problem: NikCLI cannot identify your project type

Symptoms:

Warning: Could not detect project type
Using generic development mode

Solutions:

1. Verify Project Structure:

# Check for key files
ls -la package.json tsconfig.json

# Ensure proper package.json
cat package.json | jq .dependencies

2. Add Missing Configuration:

// package.json
{
  "name": "my-project",
  "dependencies": {
    "react": "^18.0.0"  // For React detection
  }
}

3. Manual Context Setting:

# Set project context manually
nikcli context set project-type react
nikcli context set tech-stack "react,typescript,tailwind"

4. Restart from Project Root:

# Ensure running from correct directory
cd /path/to/your/project
nikcli

Git Integration Issues

Problem: Git operations failing or repository not detected

Symptoms:

Warning: Git repository not found
Git operations will be disabled

Solutions:

1. Initialize Git Repository:

git init
git add .
git commit -m "Initial commit"

2. Check Git Configuration:

git config --list
git status

3. Fix Git Permissions:

# Fix ownership issues
sudo chown -R $(whoami) .git/

# Reset permissions
chmod -R 755 .git/

4. Alternative Git Commands:

# Use NikCLI git commands
/git status
/git add .
/git commit -m "message"

File Access Permissions

Problem: NikCLI cannot read or write files

Symptoms:

Error: Permission denied accessing file: src/components/App.tsx

Solutions:

1. Check File Permissions:

ls -la src/components/App.tsx

2. Fix File Permissions:

# Make files readable/writable
chmod 644 src/components/App.tsx

# Fix directory permissions
chmod 755 src/components/

3. Check Security Settings:

# Verify security mode
nikcli security status

# Temporarily enable developer mode
nikcli dev-mode enable 30

4. Alternative Approach:

# Use explicit file operations
/read src/components/App.tsx
/write src/components/App.tsx "content"

Performance and Memory Issues

Slow Response Times

AI Responses Taking Too Long

Problem: AI model responses are slow or timing out

Symptoms:

Request timeout after 120 seconds
Retrying with exponential backoff...

Solutions:

1. Check Network Connection:

# Test internet connectivity
ping google.com

# Test specific provider
curl -I https://api.anthropic.com

2. Optimize Request Settings:

# Reduce token limits
nikcli config set token-limit 50000

# Increase timeout
nikcli config set request-timeout 180000

# Use faster model
nikcli model claude-3-haiku

3. Clear Cache:

# Clear response cache
nikcli cache clear

# Reset configuration
nikcli config reset

4. Switch Providers:

# Try different provider
nikcli model openai:gpt-3.5-turbo

High Memory Usage

Problem: NikCLI consuming excessive memory

Symptoms:

Warning: High memory usage detected (>2GB)
Consider restarting or reducing context size

Solutions:

1. Monitor Memory Usage:

# Check system memory
top -p $(pgrep node)

# Check NikCLI stats
nikcli stats

2. Reduce Context Size:

# Limit context
nikcli config set context-limit 32000

# Clear chat history
/clear

# Start new session
/new

3. Restart Application:

# Clean restart
/quit
nikcli

4. Optimize Configuration:

# Disable caching temporarily
nikcli config set cache-enabled false

# Reduce parallel operations
nikcli config set max-parallel-agents 2

Cache Issues

Problem: Outdated or corrupted cache causing problems

Symptoms:

Warning: Cache integrity check failed
Inconsistent responses detected

Solutions:

1. Clear All Caches:

# Clear response cache
nikcli cache clear

# Clear context cache
nikcli cache clear --context

# Clear all caches
nikcli cache clear --all

2. Reset Cache Directory:

# Remove cache directory
rm -rf ~/.nikcli/cache/

# Restart NikCLI
nikcli

3. Disable Caching:

# Temporary disable
nikcli config set cache-enabled false

# Test without cache
# Re-enable if needed
nikcli config set cache-enabled true

Agent and Execution Issues

Agent Failures

Agent Not Responding

Problem: Agent becomes unresponsive during execution

Symptoms:

Agent universal-agent (abc123) not responding
Last activity: 5 minutes ago

Solutions:

1. Check Agent Status:

/agents
/stream

2. Restart Specific Agent:

# Kill unresponsive agent
/kill-agent abc123

# Start new agent
/agent universal-agent "continue the task"

3. Force Restart All Agents:

# Emergency restart
/restart-agents

# Or restart NikCLI
/quit
nikcli

4. Check System Resources:

# Monitor CPU and memory
top

# Check disk space
df -h

Permission Denied Errors

Problem: Agent cannot execute required operations

Symptoms:

Error: Permission denied for operation: file-write
Security policy violation detected

Solutions:

1. Check Security Mode:

/security status

2. Adjust Security Settings:

# Enable developer mode temporarily
/dev-mode enable 60

# Or adjust specific permissions
/security set file-write-approval false

3. Manual Approval:

# Approve pending operations
/approve-all

# Or approve individually
/approve operation-id-123

4. Review Security Policies:

# Show current policies
/security policies

# Reset to defaults
/security reset

Task Execution Failures

Problem: Tasks failing with unclear error messages

Symptoms:

Task failed: Unknown error occurred
Exit code: 1

Solutions:

1. Enable Debug Mode:

# Enable verbose logging
nikcli config set log-level debug

# Check logs
tail -f ~/.nikcli/logs/debug.log

2. Break Down Complex Tasks:

# Instead of complex request, use smaller steps
> First, create the component structure
> Then, add the styling
> Finally, add the functionality

3. Use Planning Mode:

# Plan before execution
/plan create "your complex task"
/plan show
/plan execute

4. Manual Step-by-Step:

# Execute commands manually
/read src/file.ts
/edit src/file.ts
/run npm test

Configuration and Settings Issues

Configuration Corruption

Invalid Configuration Format

Problem: Configuration file is corrupted or invalid

Symptoms:

Error: Invalid configuration format
Failed to parse config.json

Solutions:

1. Validate Configuration:

# Check configuration
nikcli config validate

# Show current config
cat ~/.nikcli/config.json

2. Reset Configuration:

# Backup current config
cp ~/.nikcli/config.json ~/.nikcli/config.json.backup

# Reset to defaults
nikcli config reset

3. Manual Fix:

# Edit configuration manually
nano ~/.nikcli/config.json

# Validate JSON format
cat ~/.nikcli/config.json | jq .

4. Restore from Backup:

# If you have a backup
cp ~/.nikcli/config.json.backup ~/.nikcli/config.json

Environment Variable Conflicts

Problem: Environment variables overriding configuration

Symptoms:

Warning: Environment variable NIKCLI_MODEL overriding config
Using model: claude-3-opus instead of configured gpt-4

Solutions:

1. Check Environment Variables:

# List all NikCLI environment variables
env | grep NIKCLI
env | grep ANTHROPIC
env | grep OPENAI

2. Unset Conflicting Variables:

# Temporary unset
unset NIKCLI_MODEL
unset ANTHROPIC_API_KEY

# Remove from profile
nano ~/.bashrc  # Remove export lines

3. Use Configuration Priority:

# Force use of config file
nikcli --ignore-env

# Or set explicit precedence
nikcli config set prefer-config-over-env true

Getting Additional Help

Diagnostic Information

When reporting issues, include this diagnostic information:

System Information

# Collect system info
nikcli --version
node --version
npm --version
git --version
echo $SHELL
uname -a

Support Channels

GitHub Issues

For bugs and feature requests

Open an issue

Include:

• Detailed problem description
• Steps to reproduce
• System information
• Error logs

Documentation

Complete guides and references

• User Guide
• CLI Reference
• API Documentation
• Examples

Community Discord

Chat with other users

Join Discord

• Quick help and tips
• Share workflows
• Feature discussions
• Community support

Stack Overflow

Technical questions

Use tag: nikcli

• Programming-related questions
• Integration help
• Best practices
• Code examples

Next Steps

Performance Optimization

Learn how to optimize NikCLI performance

Debugging Guide

Advanced debugging techniques and tools

FAQ

Frequently asked questions and quick answers

Configuration Guide

Comprehensive configuration and setup guide

If you cannot find a solution to your problem, don’t hesitate to reach out through our support channels. The NikCLI community is helpful and responsive to user questions.