DevEx LogoMy App
Guides

Troubleshooting Guide

Common issues and solutions when using DevEx across different platforms and scenarios

Troubleshooting Guide

This comprehensive guide covers common issues, diagnostic techniques, and solutions for DevEx across different platforms and use cases.

Quick Diagnostics

When encountering issues, start with these diagnostic commands:

# Check DevEx status and version
devex --version
devex status

# Validate configuration
devex config validate

# Check system requirements
devex system check

# Generate diagnostic report
devex doctor --comprehensive

# Check logs
devex logs --level error --tail 50

Installation Issues

Installation Fails to Start

Symptoms:

  • Permission denied errors
  • sudo required messages
  • Cannot write to directories

Solutions:

# Fix ownership of DevEx directories
sudo chown -R $USER:$USER ~/.local/share/devex
sudo chown -R $USER:$USER ~/.devex

# Ensure binary is executable
chmod +x ~/.local/share/devex/bin/devex

# Check home directory permissions
ls -la ~ | grep -E "(devex|\.local)"

# Fix permissions if needed
chmod 755 ~/.local
chmod 755 ~/.local/share

For corporate environments:

# Use user-space installation
devex config set install.user_space_only true

# Configure alternative install directory
export DEVEX_HOME="$HOME/tools/devex"
devex config set install.prefix "$DEVEX_HOME"

Partial Installation Failures

When some applications install successfully but others fail:

Identify Failed Applications

# Check installation status
devex status --detailed

# List failed installations
devex list --status failed

# Check specific application
devex status docker

Analyze Failure Reasons

# View detailed logs
devex logs --application docker --level error

# Check system requirements
devex system check --application docker

# Validate configuration
devex config validate --application docker

Retry with Alternative Methods

# Try alternative installation method
devex install docker --method flatpak

# Skip problematic dependencies
devex install docker --skip-dependencies

# Install with elevated privileges
sudo devex install docker

Clean Up and Retry

# Clean failed installation
devex uninstall docker --force
devex cache clean --application docker

# Retry installation
devex install docker --verbose

Configuration Issues

Configuration Not Loading

Problem: DevEx not finding or loading configuration files

Diagnosis:

# Check configuration file locations
devex config paths

# Validate configuration syntax
devex config validate --strict

# Check file permissions
ls -la ~/.devex/
ls -la ~/.local/share/devex/config/

Solutions:

# Reset to default configuration
devex config reset

# Recreate configuration directory
mkdir -p ~/.devex
devex config init

# Fix configuration syntax
devex config lint --fix

# Use specific configuration file
devex config apply --file /path/to/config.yaml

Variable Resolution Issues

Problem: Variables in configuration not being resolved

Example Configuration:

# ~/.devex/variables.yaml
variables:
  nodejs_version: "18.17.0"
  company_domain: "example.com"

# ~/.devex/applications.yaml
applications:
  development:
    - name: node
      install_command: "node@${nodejs_version}"
    - name: company-cli
      install_command: "https://cli.${company_domain}/install.sh"

Solutions:

# Check variable resolution
devex config show --resolved

# Validate variable syntax
devex config validate --variables

# Debug variable resolution
devex --debug config apply --dry-run

# Use environment variables as fallback
export NODEJS_VERSION="18.17.0"
devex config set variables.nodejs_version "${NODEJS_VERSION}"

Platform-Specific Issues

Linux Issues

APT Issues (Ubuntu/Debian):

# Fix broken packages
sudo apt --fix-broken install
sudo dpkg --configure -a

# Update package lists
sudo apt update

# Clear APT cache
sudo apt clean
sudo apt autoclean

# Add missing GPG keys
devex recovery repair --apt-keys

# Reset APT sources
sudo cp /etc/apt/sources.list.d/ /etc/apt/sources.list.d.backup/
devex config apply --reset-repos

DNF Issues (Fedora/RHEL):

# Clean DNF cache
sudo dnf clean all

# Rebuild package database
sudo dnf makecache

# Fix repository issues
sudo dnf distro-sync

# Check repository configuration
devex system repositories --check

Pacman Issues (Arch):

# Update package database
sudo pacman -Sy

# Fix keyring issues
sudo pacman-key --refresh-keys

# Clear package cache
sudo pacman -Scc

# Check for partial upgrades
devex system check --pacman

macOS Issues

# Update Homebrew
brew update
brew upgrade

# Fix Homebrew permissions
sudo chown -R $(whoami) $(brew --prefix)/*

# Reinstall Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Check for conflicting installations
brew doctor

# Clean Homebrew cache
brew cleanup

Windows Issues

Winget Issues:

# Update winget
winget upgrade --id Microsoft.AppInstaller

# Reset winget sources
winget source reset

# Check winget version
winget --version

# Install from Microsoft Store if missing
# Search for "App Installer" in Microsoft Store

Chocolatey Issues:

# Update Chocolatey
choco upgrade chocolatey

# Fix Chocolatey configuration
choco feature enable -n=allowGlobalConfirmation

# Clear Chocolatey cache
choco cache clean

Application-Specific Issues

Docker Installation Problems

# Check Docker service status
sudo systemctl status docker

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Check Docker daemon logs
journalctl -u docker.service -f

# Restart Docker service
sudo systemctl restart docker

# Check Docker version
docker --version
docker info

Programming Language Issues

Node.js via mise:

# Check mise status
mise doctor

# List available Node.js versions
mise list-all node

# Install specific version
mise install node@18.17.0

# Set global version
mise global node@18.17.0

# Check Node.js installation
node --version
npm --version

# Fix npm permissions
npm config set prefix ~/.local

Python Issues:

# Check Python installation
python3 --version
pip3 --version

# Fix pip installation
python3 -m ensurepip --upgrade

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Fix package installation issues
pip install --upgrade pip setuptools wheel

Performance Issues

Slow Installation

Diagnosis:

# Check system resources
devex system resources

# Monitor installation progress
devex install --verbose --progress

# Check network speed
devex network test

# Profile installation
devex install --profile docker

Solutions:

# Enable parallel installations
devex config set install.parallel true
devex config set install.max_parallel 4

# Use faster mirrors
devex config set mirrors.use_fastest true

# Enable caching
devex config set cache.enabled true
devex config set cache.size "1GB"

# Optimize for speed
devex config set install.verify_checksums false  # Not recommended for production

Memory Issues

# Check memory usage
devex system memory

# Configure memory limits
devex config set resources.memory_limit "2GB"

# Enable swap if needed
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Clean up memory
devex cache clean
devex logs clean --older-than 7d

Recovery Procedures

Complete Environment Reset

When all else fails, completely reset your DevEx environment:

Backup Current Configuration

# Create backup
backup_dir="$HOME/devex-backup-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$backup_dir"

# Backup configurations
cp -r ~/.devex "$backup_dir/" 2>/dev/null || true
cp -r ~/.local/share/devex "$backup_dir/" 2>/dev/null || true

# Backup important files
cp ~/.bashrc "$backup_dir/bashrc.backup"
cp ~/.zshrc "$backup_dir/zshrc.backup" 2>/dev/null || true

Complete Removal

# Stop all DevEx processes
devex stop --all

# Uninstall all applications
devex uninstall --all --force

# Remove DevEx completely
rm -rf ~/.local/share/devex
rm -rf ~/.devex

# Clean PATH
sed -i '/devex/d' ~/.bashrc
sed -i '/devex/d' ~/.zshrc 2>/dev/null || true

Fresh Installation

# Fresh DevEx installation (review security guide first)
curl -fsSL https://devex.sh/install | bash

# Reload shell
source ~/.bashrc

# Verify installation
devex --version
devex doctor

Restore Configuration

# Restore custom configurations
cp -r "$backup_dir/.devex" ~/

# Apply restored configuration
devex config validate
devex install

Service Recovery

For applications with persistent services:

# Docker recovery
devex recovery docker --full-reset

# Database recovery
devex recovery postgresql --repair-data

# System service recovery
devex recovery services --restart-all

Getting Help

Debug Information Collection

When reporting issues, collect this information:

# Generate comprehensive diagnostic report
devex doctor --comprehensive --output devex-diagnostic.txt

# System information
devex system info --detailed

# Configuration dump
devex config dump --sanitized

# Recent logs
devex logs --since "1 hour ago" --level error

# Package manager status
devex system package-managers --status

Community Support

GitHub Issues

Report bugs and request features

Discussions

Community Q&A and discussions

Documentation

Complete documentation

Examples

Real-world usage examples

Creating Bug Reports

When creating bug reports, include:

  1. DevEx version: devex --version
  2. Operating system: devex system info
  3. Configuration files: Sanitized configuration files
  4. Error messages: Complete error output
  5. Steps to reproduce: Detailed reproduction steps
  6. Expected behavior: What should have happened
  7. Diagnostic report: Output from devex doctor

Prevention is Better Than Cure:

  1. Regular Updates: Keep DevEx and applications updated
  2. Configuration Backups: Regularly backup your configurations
  3. Validation: Validate configurations before applying
  4. Monitoring: Monitor system resources and logs
  5. Documentation: Document any customizations
  6. Testing: Test changes in safe environments first

Advanced Debugging

For complex issues:

# Enable trace mode
export DEVEX_TRACE=1
export DEVEX_DEBUG=1

# Run with maximum verbosity
devex --verbose --log-level trace install problematic-app

# Use debugging tools
strace -o devex.trace devex install app
ltrace -o devex.ltrace devex install app

# Analyze system calls
grep -E "(open|read|write|exec)" devex.trace

Remember: Most issues have simple solutions. Start with basic troubleshooting before moving to advanced techniques.

Getting Started

Basic DevEx usage guide

Configuration

Configuration reference

CLI Reference

Complete command reference

Platform Support

Platform-specific information

Automation Guide

Automate DevEx in CI/CD pipelines, deployment scripts, and infrastructure automation

Examples Overview

Real-world DevEx configurations and use cases for different development scenarios

On this page

Troubleshooting GuideQuick DiagnosticsInstallation IssuesInstallation Fails to StartPartial Installation FailuresIdentify Failed ApplicationsAnalyze Failure ReasonsRetry with Alternative MethodsClean Up and RetryConfiguration IssuesConfiguration Not LoadingVariable Resolution IssuesPlatform-Specific IssuesLinux IssuesmacOS IssuesWindows IssuesApplication-Specific IssuesDocker Installation ProblemsProgramming Language IssuesPerformance IssuesSlow InstallationMemory IssuesRecovery ProceduresComplete Environment ResetBackup Current ConfigurationComplete RemovalFresh InstallationRestore ConfigurationService RecoveryGetting HelpDebug Information CollectionCommunity SupportCreating Bug ReportsAdvanced Debugging