Troubleshooting¶
Common issues and solutions for codebrief users.
Installation Issues¶
Poetry Installation Problems¶
Problem: poetry install fails or takes too long
Solutions:
# Clear poetry cache
poetry cache clear pypi --all
# Install with verbose output
poetry install -vvv
# Use pip install as fallback
pip install -e .
Python Version Compatibility¶
Problem: Unsupported Python version errors
Solutions:
# Check your Python version
python --version
# Install compatible Python version (3.9+)
# macOS with Homebrew
brew install python@3.11
# Ubuntu/Debian
sudo apt install python3.11
# Use pyenv for version management
pyenv install 3.11.0
pyenv local 3.11.0
Permission Errors¶
Problem: Permission denied during installation
Solutions:
# Use virtual environment
python -m venv codebrief-env
source codebrief-env/bin/activate # Linux/macOS
# codebrief-env\Scripts\activate # Windows
# Install in user directory
pip install --user -e .
Runtime Issues¶
Command Not Found¶
Problem: codebrief: command not found
Solutions:
# Activate poetry shell
poetry shell
# Use poetry run prefix
poetry run codebrief --help
# Check installation
which codebrief
poetry show codebrief
Git Repository Not Found¶
Problem: "Not a git repository" errors
Solutions:
# Initialize git repository
git init
git add .
git commit -m "Initial commit"
# Run from project root
cd /path/to/your/project
codebrief tree
# Specify project path
codebrief tree /path/to/project
File Permission Issues¶
Problem: Permission denied when reading/writing files
Solutions:
# Check file permissions
ls -la
# Fix permissions
chmod 755 /path/to/directory
chmod 644 /path/to/file
# Run with appropriate user
sudo chown -R $USER:$USER /path/to/project
Output Issues¶
Empty or Missing Output¶
Problem: Commands complete but produce no output
Check List: 1. File Patterns: Verify include/exclude patterns 2. Directory Path: Ensure correct project path 3. File Extensions: Check if files match patterns 4. Permissions: Verify read access to files
Debug Steps:
# Test with verbose output
codebrief tree --help
# Check file detection
ls -la src/ # Verify files exist
# Test basic command
codebrief tree .
Encoding Issues¶
Problem: Unicode/encoding errors in output
Solutions:
# Set UTF-8 encoding
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
# Force UTF-8 output
codebrief tree --output output.md
file output.md # Check file encoding
Large Output Files¶
Problem: Output files are too large or cause performance issues
Solutions:
# Use focused context
codebrief flatten src/ --include "*.py" --exclude "*test*"
# Exclude large directories
codebrief tree --ignore "node_modules/" "venv/" "__pycache__/"
# Split into smaller files
codebrief flatten src/core/ --output core.md
codebrief flatten src/utils/ --output utils.md
Configuration Issues¶
Configuration Not Loading¶
Problem: Settings in pyproject.toml not applied
Solutions:
# Verify file location
ls -la pyproject.toml
# Check TOML syntax
poetry check
# Test with explicit config
codebrief tree --output custom-output.txt
Invalid Configuration Format¶
Problem: Configuration validation errors
Solutions:
# Correct configuration format
[tool.codebrief]
default_output_filename_tree = "project-tree.txt"
global_exclude_patterns = [
"*.log",
"*.tmp",
"__pycache__/"
]
Git Integration Issues¶
Git Command Failures¶
Problem: Git-related commands fail
Solutions:
# Check git installation
git --version
# Verify repository status
git status
# Check git configuration
git config --list
# Test git log access
git log --oneline -n 5
Missing Git History¶
Problem: Git info shows no commits or limited history
Solutions:
# Check git log
git log --oneline
# Verify repository depth (for clones)
git log --oneline | wc -l
# For shallow clones
git fetch --unshallow
Git Diff Issues¶
Problem: Git diff output is empty or incorrect
Solutions:
# Check for staged changes
git status
# Verify diff options
git diff --stat
# Use specific git options
codebrief git-info --diff-options "--name-only"
Performance Issues¶
Slow Execution¶
Problem: Commands take too long to complete
Optimization Strategies:
# Use focused patterns
codebrief flatten src/ --include "*.py"
# Exclude large directories
codebrief tree --ignore "node_modules/" "build/" "dist/"
# Process in parallel (custom script)
# See Advanced Workflows documentation
Memory Issues¶
Problem: Out of memory errors with large projects
Solutions:
# Process smaller sections
codebrief flatten src/module1/ --output module1.md
codebrief flatten src/module2/ --output module2.md
# Use exclude patterns
codebrief tree --ignore "*.log" "*.tmp" "__pycache__/"
# Limit git history
codebrief git-info --log-count 5
Dependency Analysis Issues¶
No Dependencies Found¶
Problem: codebrief deps shows no dependencies
Check List: 1. File Names: Verify dependency files exist 2. File Formats: Check supported formats (pyproject.toml, package.json) 3. File Content: Ensure files have valid syntax 4. Directory: Run from project root
Debug Steps:
# List dependency files
ls -la pyproject.toml package.json requirements*.txt
# Verify file content
head pyproject.toml
python -c "import toml; print(toml.load('pyproject.toml'))"
Parsing Errors¶
Problem: Dependency file parsing fails
Solutions:
# Validate TOML files
poetry check # For pyproject.toml
# Validate JSON files
python -m json.tool package.json # For package.json
# Check file encoding
file pyproject.toml
CI/CD Integration Issues¶
GitHub Actions Failures¶
Problem: codebrief fails in CI/CD pipelines
Common Solutions:
# Ensure full git history
- uses: actions/checkout@v4
with:
fetch-depth: 0
# Install dependencies properly
- name: Install Poetry
uses: snok/install-poetry@v1
- name: Install Dependencies
run: poetry install
# Set proper permissions
- name: Fix Permissions
run: chmod -R 755 .
Test Environment Differences¶
Problem: Works locally but fails in CI
Debug Steps: 1. Environment Variables: Check env output 2. File Permissions: Verify file access 3. Dependencies: Ensure same versions 4. Git Configuration: Check git setup
Common Error Messages¶
"No such file or directory"¶
Cause: File path is incorrect or file doesn't exist
Solution:
# Check current directory
pwd
# List files
ls -la
# Use absolute paths
codebrief tree /full/path/to/project
"Permission denied"¶
Cause: Insufficient file/directory permissions
Solution:
# Fix permissions
chmod 755 directory/
chmod 644 file.txt
# Check ownership
ls -la
sudo chown $USER:$USER file.txt
"Not a git repository"¶
Cause: Running git commands outside git repository
Solution:
"Command not found"¶
Cause: codebrief not in PATH or not installed
Solution:
# Activate poetry environment
poetry shell
# Or use poetry run
poetry run codebrief --help
# Check installation
which codebrief
Getting Help¶
Debug Information¶
When reporting issues, include:
# System information
uname -a # System details
python --version # Python version
poetry --version # Poetry version
git --version # Git version
# codebrief information
poetry run codebrief --version
poetry show codebrief
# Environment details
pwd # Current directory
ls -la # Directory contents
git status # Git status (if applicable)
Community Support¶
- GitHub Issues: Report bugs and request features
- GitHub Discussions: Community help and questions
- Documentation: Complete documentation
Professional Support¶
For enterprise users requiring dedicated support: - Contact through GitHub Issues with [Enterprise] tag - See Security Policy for security-related issues
Prevention Tips¶
Best Practices¶
- Use Virtual Environments: Always use poetry or venv
- Regular Updates: Keep dependencies updated
- Test Locally: Test commands before CI/CD
- Configuration Management: Use consistent configurations
- Documentation: Keep team documentation updated