troubleshooting.md

DMtools Installation Troubleshooting

Back to README installation

🔍 Common Installation Issues

Issue: "Java version not found" or "Java 17+ required"

Symptoms:

Error: Java 17 or higher is required. Current version: 11

Solutions:

1. Let the installer handle it:

   # Re-run installer, it will install Java automatically
   curl -fsSL https://github.com/epam/dm.ai/releases/latest/download/install.sh | bash

2. Manual Java installation:

   # Using SDKMAN
   curl -s "https://get.sdkman.io" | bash
   source "$HOME/.sdkman/bin/sdkman-init.sh"
   sdk install java 17-open
   sdk default java 17-open

3. Verify Java is in PATH:

   which java
   java -version
   echo $JAVA_HOME

Issue: "dmtools: command not found"

Symptoms:

$ dmtools --version
bash: dmtools: command not found

Solutions:

1. Reload your shell configuration:

   source ~/.bashrc  # or ~/.zshrc for macOS

2. Check if alias exists:

   alias | grep dmtools
   # Should show: alias dmtools='java -jar /home/user/.dmtools/dmtools.jar'

3. Manually add to PATH:

   echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
   echo 'alias dmtools="java -jar ~/.dmtools/dmtools.jar"' >> ~/.bashrc
   source ~/.bashrc

4. Check if JAR exists:

   ls -la ~/.dmtools/dmtools.jar
   # Should show the JAR file

Issue: "Permission denied" during installation

Symptoms:

curl: (23) Failed writing body
mkdir: cannot create directory '/home/user/.dmtools': Permission denied

Solutions:

1. Fix directory permissions:

   sudo chown -R $USER:$USER ~/
   chmod 755 ~/

2. Create directories manually:

   mkdir -p ~/.dmtools ~/bin
   chmod 755 ~/.dmtools ~/bin

3. Re-run installer:

   curl -fsSL https://github.com/epam/dm.ai/releases/latest/download/install.sh | bash

Issue: "Network error" or "Failed to download"

Symptoms:

curl: (7) Failed to connect to raw.githubusercontent.com
wget: unable to resolve host address 'github.com'

Solutions:

1. Check internet connection:

   ping -c 3 github.com
   curl -I https://github.com

2. Use proxy if required:

   export HTTP_PROXY=http://proxy.company.com:8080
   export HTTPS_PROXY=http://proxy.company.com:8080
   curl -fsSL https://github.com/epam/dm.ai/releases/latest/download/install.sh | bash

3. Download manually:

   # Download via browser, then:
   java -jar ~/Downloads/dmtools-v1.7.179-all.jar --version

4. Use alternative download method:

   # Using wget instead of curl
   wget -O - https://github.com/epam/dm.ai/releases/latest/download/install.sh | bash

🖥️ Platform-Specific Issues

macOS Issues

"Operation not permitted" on macOS

# Grant Terminal full disk access:
# System Preferences → Security & Privacy → Privacy → Full Disk Access
# Add Terminal.app or iTerm2

Homebrew Java conflicts

# Check Java installations
brew list | grep openjdk

# Unlink old version
brew unlink openjdk@11

# Link Java 17
brew link openjdk@17

Windows WSL Issues

WSL not installed

# In PowerShell as Administrator
wsl --install
# Restart computer

Java installation in WSL

# In WSL terminal
sudo apt update
sudo apt install openjdk-17-jdk

Path issues in WSL

# Add to ~/.bashrc
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

Linux Issues

Missing dependencies

# Ubuntu/Debian
sudo apt update
sudo apt install curl wget unzip

# RHEL/CentOS
sudo yum install curl wget unzip

# Arch
sudo pacman -S curl wget unzip

🔧 Runtime Issues

Issue: "Out of memory" error

Symptoms:

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space

Solutions:

1. Increase heap size in wrapper script:

   # Edit ~/bin/dmtools
   java -Xmx2g -jar ~/.dmtools/dmtools.jar "$@"

2. Set via environment variable:

   export JAVA_OPTS="-Xmx2g -Xms512m"
   dmtools run agents/large_task.json

Issue: "Class not found" or "NoClassDefFoundError"

Symptoms:

Exception in thread "main" java.lang.NoClassDefFoundError

Solutions:

1. Re-download the JAR:

   rm ~/.dmtools/dmtools.jar
   curl -fsSL https://github.com/epam/dm.ai/releases/latest/download/install.sh | bash

2. Check JAR integrity:

   jar tf ~/.dmtools/dmtools.jar | head -20
   # Should list class files

Issue: SSL/TLS certificate errors

Symptoms:

javax.net.ssl.SSLHandshakeException: PKIX path building failed

Solutions:

1. Update CA certificates:

   # Ubuntu/Debian
   sudo apt-get update && sudo apt-get install ca-certificates
   
   # macOS
   brew install ca-certificates

2. Disable SSL verification (NOT recommended for production):

   export JAVA_OPTS="-Dcom.sun.net.ssl.checkRevocation=false"

🐛 Debug Mode

Enable debug output for troubleshooting:

# Run with debug flag
dmtools --debug list

# Set debug environment variable
export DMTOOLS_DEBUG=true
dmtools list

# Check Java system properties
java -XshowSettings:properties -jar ~/.dmtools/dmtools.jar --version

📋 Diagnostic Commands

Run these commands to gather system information for bug reports:

# System information
echo "=== System Info ==="
uname -a
echo "=== Java Version ==="
java -version
echo "=== Java Location ==="
which java
echo "=== JAVA_HOME ==="
echo $JAVA_HOME
echo "=== DMtools Location ==="
ls -la ~/.dmtools/
echo "=== Shell ==="
echo $SHELL
echo "=== PATH ==="
echo $PATH
echo "=== Alias ==="
alias | grep dmtools
echo "=== DMtools Version ==="
dmtools --version 2>&1

🆘 Getting Help

If these solutions don't resolve your issue:

1. Check existing issues:

   • GitHub Issues

2. Create a new issue with:

   • Output from diagnostic commands above
   • Complete error message
   • Steps to reproduce
   • Operating system and version
   • Java version

3. Community support:

   • Include #dmtools tag in your question
   • Provide context about your environment

🔄 Clean Reinstall

If all else fails, perform a clean reinstall:

# 1. Remove all DMtools files
rm -rf ~/.dmtools
rm ~/bin/dmtools

# 2. Remove from shell config
# Edit ~/.bashrc or ~/.zshrc and remove DMtools lines

# 3. Clear Java cache
rm -rf ~/.java/

# 4. Reinstall
curl -fsSL https://github.com/epam/dm.ai/releases/latest/download/install.sh | bash

# 5. Reload shell
exec $SHELL

---

Still having issues? Report at github.com/epam/dm.ai/issues