Troubleshooting

Common Issues

Environment Setup

'.env not found' error

Problem: The system can’t find your environment configuration file.Solution:

npx mega-brain-ai setup

The setup wizard will:

Create a .env file in your project root
Prompt for required API keys
Configure optional integrations
Validate your environment

Setup auto-triggers on first use if .env is missing, so you may not need to run this manually.

API key not working

Problem: Commands fail with authentication errors.Check:

Verify your .env file exists in the project root
Ensure OPENAI_API_KEY is set (required for transcription)
Check for extra spaces or quotes around keys
Restart Claude Code after changing .env

Format:

# Correct
OPENAI_API_KEY=sk-proj-...

# Wrong (extra quotes)
OPENAI_API_KEY="sk-proj-..."

# Wrong (extra spaces)
OPENAI_API_KEY= sk-proj-...

Run /setup to reconfigure keys interactively and validate the format.

Python & Hooks

'Hook failed' errors

Problem: Hooks fail to execute with Python errors.Solutions:

Check Python version:

python --version  # Should be 3.10 or higher

Verify Python is in PATH:

which python  # Unix/Mac
where python  # Windows

Install PyYAML (only external dependency for hooks):
```
pip install pyyaml
```
Check hook permissions (Unix/Mac):
```
chmod +x .claude/hooks/*.py
```

Hooks use only stdlib + PyYAML to minimize dependency issues.

Hook runs but doesn't work as expected

Problem: Hook executes without errors but behavior is wrong.Debug steps:

Check hook configuration in settings.json:

{
  "hooks": {
    "SessionStart": [".claude/hooks/session_start.py"],
    "UserPromptSubmit": [".claude/hooks/skill_router.py"]
  }
}

Add debug output to your hook:

import sys
print(f"DEBUG: Hook triggered with {len(sys.argv)} args", file=sys.stderr)

Check hook event timing:
- SessionStart - Runs once when Claude starts
- UserPromptSubmit - Runs before each user message
- PreToolUse - Runs before tool execution
- PostToolUse - Runs after tool execution
- Stop - Runs when session ends

Skills & Auto-Routing

Skills not auto-activating

Problem: Skills don’t activate when you expect them to.Check:

Verify SKILL-INDEX.json exists:
```
ls .claude/SKILL-INDEX.json
```
If missing, it should be generated on SessionStart by skill_indexer.py hook.

Verify skill description is specific:

# Too vague (won't trigger)
description: Helps with files

# Specific (will trigger)
description: Extract DNA from expert materials. Use when processing videos, PDFs, or transcriptions.

Check skill file structure:

.claude/skills/skill-name/
├── SKILL.md          # Must be exactly this name
└── resources/

Validate YAML frontmatter:

---
name: skill-name      # Must match directory name
description: Clear description with trigger words
---

Include “Use when…” context in your skill description with specific trigger words users would say.

Skill not found error

Problem: Skill doesn’t appear in available skills list.Check:

File location:

# Project skills
ls .claude/skills/skill-name/SKILL.md

# Personal skills (if using)
ls ~/.claude/skills/skill-name/SKILL.md

Filename is exact (case-sensitive):
- ✅ Correct: SKILL.md
- ❌ Wrong: skill.md, Skill.md, SKILL.MD

Directory name matches frontmatter:

Directory: knowledge-extraction/
Frontmatter: name: knowledge-extraction  # Must match

Restart Claude Code to reload skills

YAML parsing errors in skills

Problem: Skill fails to load with parsing errors.Common issues:

Tabs in YAML (use spaces only):

# Wrong (contains tabs)
name:	skill-name

# Correct (spaces only)
name: skill-name

Missing frontmatter delimiters:

---              # Line 1 (no blank lines before)
name: skill-name
description: ...
---              # Required closing delimiter

# Content starts here

Validate your YAML:

head -n 10 .claude/skills/skill-name/SKILL.md

# Check for tabs (should return nothing)
grep -P '\t' .claude/skills/skill-name/SKILL.md

Git & Version Control

'Permission denied on git push'

Problem: Git push is blocked.This is by design:

git push is blocked by settings.json deny rules
Direct pushes to main are prohibited
Use the branch + PR workflow instead

Correct workflow:

# 1. Create feature branch
git checkout -b feat/my-feature

# 2. Make changes and commit
git add .
git commit -m "feat: add new feature"

# 3. Push branch (not main)
git push origin feat/my-feature

# 4. Open PR on GitHub

If you need to push to main for a legitimate reason, delegate to @devops or contact the maintainer.

Pipeline Processing

Pipeline fails at Phase 1 (Chunking)

Problem: /process-jarvis fails during chunking phase.Common causes:

File not in inbox:
```
ls inbox/
```
Make sure your file was ingested with /ingest first.
File format not supported:
- ✅ Supported: .md, .txt, .pdf, .mp4, .mp3
- ❌ Not supported: Binary formats without extractors
OpenAI API key missing (for transcription):
```
# Check .env
grep OPENAI_API_KEY .env
```
File too large:
- Check if file exceeded API limits
- Consider splitting large files

Pipeline completes but no output

Problem: Pipeline runs successfully but doesn’t generate expected outputs.Check:

Artifacts directory:

ls -la artifacts/chunks/
ls -la artifacts/insights/
ls -la artifacts/narratives/

Knowledge directory:

ls -la knowledge/dossiers/
ls -la knowledge/playbooks/

Session logs:

ls -la logs/sessions/
# Check latest log for errors

Check /jarvis-briefing for health score and errors

Agent & Conclave

Agent commands not working

Problem: Slash commands for agents return errors.Check:

Agent exists in AGENT-INDEX.yaml:

grep "name: agent-name" agents/AGENT-INDEX.yaml

Agent files present:

ls agents/cargo/agent-name/
ls agents/persons/agent-name/

Memory directory exists:
```
ls .claude/agent-memory/agent-name/
```

Command syntax:

# Correct
/conclave "Should I hire a CMO or outsource marketing?"

# Wrong (missing quotes)
/conclave Should I hire a CMO?

Conclave returns low confidence

Problem: Council sessions show low confidence scores.This is expected when:

Limited knowledge base (process more materials)
Few relevant experts (add more diverse sources)
Complex question with limited context

Improve confidence by:

Processing more expert materials
Creating DNA extractions from specialists
Providing more context in your question
Building up relevant playbooks

The system is transparent about confidence levels. Low confidence means “I don’t have enough data to be certain” - which is honest and valuable feedback.

Installation Issues

npm install fails

Problem: Package installation errors.Solutions:

Check Node version:
```
node --version  # Should be >= 18.0.0
```

Clear cache and reinstall:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Check for permission issues:

# Unix/Mac (if global install fails)
sudo npm install -g mega-brain-ai

Python dependencies missing

Problem: Intelligence scripts fail with import errors.Solution:

# Install all Python dependencies
pip install -r requirements.txt

# Or install individually
pip install pyyaml

Python 3.10+ required. Earlier versions may have compatibility issues.

Performance Issues

Slow processing times

Problem: Pipeline or commands take too long.Optimize:

Check file sizes:
- Large videos take longer to transcribe
- Consider processing audio separately
Review API rate limits:
- OpenAI Whisper has rate limits
- Space out large batch processing

Monitor resource usage:

# Check system resources
top  # Unix/Mac
taskmgr  # Windows

Process in batches:
- Don’t ingest 50 files at once
- Process 3-5 files, then review

Session Management

Session won't save

Problem: /save command fails.Check:

Logs directory exists:
```
mkdir -p logs/sessions
```
Permissions:
```
# Unix/Mac
chmod 755 logs/sessions
```
Disk space:
```
df -h  # Unix/Mac
```

Can't resume previous session

Problem: /resume doesn’t work.Check:

Session files exist:
```
ls -la logs/sessions/
```
Session format is valid:
- Sessions are stored as JSON
- Check for corruption
Try listing sessions:
```
/resume --list  # If supported
```

Getting Help

Still Having Issues?

Check system status: Run /jarvis-briefing for health score
Review logs: Check logs/sessions/ for detailed error messages
Search existing issues: Check GitHub issues for similar problems
Open an issue: Provide:
- Error message (full text)
- Command you ran
- System info (OS, Node version, Python version)
- Relevant log files
Contact maintainer: Reach out to @thiagofinch

Before reporting an issue, run these diagnostic commands:

node --version
python --version
npm list mega-brain-ai
ls -la .env
/jarvis-briefing

Include the output in your issue report.

Resources

Common Issues

Environment Setup

Python & Hooks

Skills & Auto-Routing

Git & Version Control

Pipeline Processing

Agent & Conclave

Installation Issues

Performance Issues

Session Management

Getting Help

Still Having Issues?

Build docs developers (and LLMs) love

Resources

​Common Issues

​Environment Setup

​Python & Hooks

​Skills & Auto-Routing

​Git & Version Control

​Pipeline Processing

​Agent & Conclave

​Installation Issues

​Performance Issues

​Session Management

​Getting Help

Still Having Issues?

Build docs developers (and LLMs) love

Common Issues

Environment Setup

Python & Hooks

Skills & Auto-Routing

Git & Version Control

Pipeline Processing

Agent & Conclave

Installation Issues

Performance Issues

Session Management

Getting Help