Common Issues Troubleshooting Guide¶
Last Updated: 2026-07-11 Version: v0.2.0
Version: 1.0.0
Last Updated: 2026-06-22
Quick Diagnostics¶
Check Environment¶
# Python version
python --version # Should be 3.10+
# Installed packages
pip list | grep codex
# Environment variables
env | grep CODEX
Check Installation¶
# Verify codex is importable
python -c "import codex; print('OK')"
# Check ML components
python -c "from codex_ml import __version__; print(__version__)"
Common Issues¶
1. Import Errors¶
Symptom: ModuleNotFoundError: No module named 'codex'
Solutions:
# Reinstall in development mode
pip install -e .
# Or with uv
uv pip install -e .
# Verify PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"
2. Test Failures¶
Symptom: Tests fail with import errors or missing fixtures
Solutions:
# Install test dependencies
pip install -e ".[dev]"
# Run with correct paths
PYTHONPATH=src pytest tests/ -v
# Check for missing conftest.py
ls tests/conftest.py
3. Database Connection Issues¶
Symptom: sqlite3.OperationalError or connection timeouts
Solutions:
# Check database path
echo $CODEX_LOG_DB_PATH
# Create directory if missing
mkdir -p .codex
# Reset database
rm -f .codex/agent_memory.db
4. Memory/Performance Issues¶
Symptom: High memory usage or slow execution
Solutions:
# Enable CPU-only mode
import os
os.environ['CODEX_FORCE_CPU'] = '1'
# Limit batch sizes
os.environ['CODEX_BATCH_SIZE'] = '16'
5. CI/CD Pipeline Failures¶
Symptom: GitHub Actions workflow fails
Diagnostic Steps:
- Check workflow logs in GitHub Actions
- Look for specific error messages
- Run locally with same environment:
# Set CI environment
export CI=true
export PYTEST_DISABLE_PLUGIN_AUTOLOAD=1
# Run tests
nox -s tests
6. Linting/Formatting Errors¶
Symptom: Pre-commit hooks fail
Solutions:
# Auto-fix formatting
black src/ tests/
isort src/ tests/
# Check specific files
ruff check src/codex_ml/path/to/file.py --fix
7. Type Checking Errors¶
Symptom: mypy reports type errors
Solutions:
# Run mypy with config
mypy src/codex_ml/ --config-file pyproject.toml
# Ignore specific errors (last resort)
# Add: # type: ignore[error-code]
Environment Variables¶
| Variable | Purpose | Default |
|---|---|---|
CODEX_SESSION_ID |
Session identifier | Auto-generated |
CODEX_SESSION_LOG_DIR |
Log directory | .codex/sessions |
CODEX_LOG_DB_PATH |
SQLite database path | .codex/session_logs.db |
CODEX_FORCE_CPU |
Disable GPU | 0 |
PYTEST_DISABLE_PLUGIN_AUTOLOAD |
Disable pytest plugins | Not set |
Diagnostic Commands¶
Full System Check¶
# Run all checks
./maintenance.sh check
# Or manually:
python -m py_compile src/codex_ml/*.py
ruff check src/
mypy src/codex_ml/
pytest tests/unit/ -v --tb=short
Log Analysis¶
# View recent logs
tail -f .codex/sessions/*.log
# Search for errors
grep -r "ERROR\|Exception" .codex/sessions/
Resource Usage¶
# Memory usage during tests
/usr/bin/time -v pytest tests/ -x
# Profile specific test
python -m cProfile -o profile.out -m pytest tests/unit/test_specific.py
Getting Help¶
- Search Issues: GitHub Issues
- Check Docs:
docs/directory - AI Assistance: Use prompts in
agents/prompts/debugging/ - Ask Questions: Open a new issue with details
Reporting Issues¶
When reporting issues, include:
- Environment: Python version, OS, installed packages
- Steps to Reproduce: Minimal example
- Expected vs Actual: What should happen vs what happened
- Logs: Relevant error messages and stack traces
- Context: What were you trying to accomplish?