Troubleshooting

Common Issues and Solutions

Installation Issues

IVPM Command Not Found

Problem: ivpm: command not found

Solutions:

Check installation:
```
$ python3 -m pip list | grep ivpm
```
Install if missing:
```
$ python3 -m pip install --user ivpm
```

Check PATH:

$ echo $PATH | grep -o ~/.local/bin

If not present, add to ~/.bashrc:

export PATH="$HOME/.local/bin:$PATH"

Use Python module form:
```
$ python3 -m ivpm --help
```

Python Version Mismatch

Problem: IVPM requires Python 3.x but system has 2.x

Solutions:

# Use python3 explicitly
$ python3 -m pip install --user ivpm
$ python3 -m ivpm update

Update Issues

SSH Authentication Failed

Problem: Permission denied (publickey) when cloning

Cause: SSH key not configured or not registered with Git server

Solutions:

Use anonymous cloning:

$ ivpm update -a

Or in ivpm.yaml:

deps:
  - name: package
    url: https://github.com/org/package.git
    anonymous: true

Configure SSH key:

# Generate key if needed
$ ssh-keygen -t ed25519 -C "your_email@example.com"

# Add to GitHub/GitLab
$ cat ~/.ssh/id_ed25519.pub
# Copy and add to GitHub Settings → SSH Keys

Test SSH connection:
```
$ ssh -T git@github.com
```

Package Already Exists

Problem: Directory packages/xyz already exists

Cause: Dependency already fetched, possibly stale

Solutions:

# Remove and re-fetch
$ rm -rf packages/xyz
$ ivpm update

# Or remove all and start fresh
$ rm -rf packages/
$ ivpm update

Git Clone Failed

Problem: Git clone errors (timeout, network, etc.)

Solutions:

Check connectivity:

$ ping github.com
$ curl -I https://github.com

Try anonymous:
```
$ ivpm update -a
```

Check firewall/proxy:

# Set HTTP proxy if needed
$ export HTTP_PROXY=http://proxy:port
$ export HTTPS_PROXY=http://proxy:port

Use local mirror:

deps:
  - name: package
    url: https://internal-mirror.com/package.git

Dependency Not Found

Problem: Package xyz not found or similar

Cause: Typo, wrong dependency set, or package doesn’t exist

Solutions:

Check spelling:

# Wrong
- name: reqeusts  # Typo
  src: pypi

# Correct
- name: requests
  src: pypi

Check dependency set:

$ cat ivpm.yaml  # Verify dep-set
$ ivpm update -d default-dev  # Explicit set

Verify package exists:

# For PyPI
$ python3 -m pip search package-name

# For Git
$ git ls-remote https://github.com/org/package.git

Python Package Issues

Module Not Found

Problem: ModuleNotFoundError: No module named 'xyz'

Cause: Package not installed, or not in active environment

Solutions:

Verify installation:

$ ivpm activate -c "pip list | grep xyz"

Force reinstall:
```
$ ivpm update --force-py-install
```

Check dependency set:

$ ivpm update -d default-dev  # Ensure correct set

Check if package is Python type:

# Add type if auto-detection fails
- name: xyz
  url: https://github.com/org/xyz.git
  type: python

Editable Install Not Working

Problem: Changes to package source not reflected

Cause: Package not installed in editable mode

Solutions:

Check installation mode:

$ ivpm activate -c "pip list | grep xyz"
# Should show: xyz  <version>  <path-to-packages>

Verify egg-link:

$ ls packages/python/lib/python*/site-packages/*.egg-link

Reinstall:
```
$ ivpm update --force-py-install
```

Check package has setup.py:

$ ls packages/xyz/setup.py  # Must exist

Version Conflict

Problem: ERROR: Cannot install xyz because these package versions have incompatible dependencies

Cause: Version requirements conflict between packages

Solutions:

Identify conflict:
```
$ ivpm activate -c "pip check"
```

Adjust version specs:

# Too restrictive
- name: package-a
  src: pypi
  version: "==1.0.0"

# More flexible
- name: package-a
  src: pypi
  version: ">=1.0.0,<2.0"

Check dependency tree:

$ ivpm activate -c "pip show package-name"

Native Extension Build Failed

Problem: Errors when building C/C++ extensions

Cause: Missing compiler, headers, or build dependencies

Solutions:

Install build tools:

# Ubuntu/Debian
$ sudo apt-get install build-essential python3-dev

# macOS
$ xcode-select --install

# Windows
# Install Visual Studio Build Tools

Check setup-deps:

setup-deps:
  - cython
  - setuptools
  - wheel

Debug build:

$ ivpm build --debug
$ ivpm activate -c "python setup.py build_ext --verbose"

Cache Issues

Cache Not Working

Problem: Packages not being cached

Cause: IVPM_CACHE not set or cache not enabled

Solutions:

Set environment variable:

$ export IVPM_CACHE=~/.cache/ivpm
$ ivpm cache init $IVPM_CACHE

Enable in ivpm.yaml:

deps:
  - name: package
    url: https://github.com/org/package.git
    cache: true

Verify:

$ echo $IVPM_CACHE
$ ls -la $IVPM_CACHE

Broken Symlinks

Problem: Symlinks in packages/ point to non-existent cache entries

Cause: Cache was cleaned or manually deleted

Solutions:

# Remove broken symlinks
$ find packages/ -type l ! -exec test -e {} \; -delete

# Re-fetch packages
$ ivpm update

Cache Permission Denied

Problem: Cannot write to shared cache

Cause: Incorrect permissions on shared cache

Solutions:

Check permissions:
```
$ ls -ld /shared/ivpm-cache
```

Add to group:

$ sudo usermod -a -G devteam $USER
$ newgrp devteam  # Or logout/login

Fix permissions:

$ sudo chmod g+s /shared/ivpm-cache
$ sudo chmod -R g+rw /shared/ivpm-cache

Git Issues

Detached HEAD State

Problem: Git shows “detached HEAD” warning

Cause: Checked out a tag or specific commit

This is normal for tags/commits. Not an error.

To fix if unintended:

$ cd packages/package-name
$ git checkout main  # Or any branch
$ cd ../..

Merge Conflicts

Problem: ivpm sync fails with merge conflicts

Cause: Local and remote changes conflict

Solutions:

$ cd packages/conflicted-package

# Option 1: Keep local changes
$ git status  # See conflicts
$ # Edit conflicted files
$ git add .
$ git commit

# Option 2: Discard local changes
$ git reset --hard origin/main

# Option 3: Stash and reapply
$ git stash
$ git pull
$ git stash pop

$ cd ../..

Submodule Not Initialized

Problem: Submodule directories empty

Cause: Submodules not initialized

Solutions:

# Manual initialization
$ cd packages/repo-with-submodules
$ git submodule update --init --recursive
$ cd ../..

# Or re-fetch with IVPM
$ rm -rf packages/repo-with-submodules
$ ivpm update

Cannot Push Changes

Problem: Cannot push to Git repository

Cause: No write access or wrong remote URL

Solutions:

Check remote:

$ cd packages/package-name
$ git remote -v

Change to SSH:

$ git remote set-url origin git@github.com:user/package.git

Use fork:

$ git remote add myfork git@github.com:me/package.git
$ git push myfork branch-name

Environment Issues

Variables Not Set

Problem: Environment variables not available

Cause: Not using ivpm activate or env-sets not defined

Solutions:

Use activate:
```
$ ivpm activate -c "echo \$MY_VAR"
```

Check env-sets:

$ cat ivpm.yaml  # Verify env-sets section

Re-run update:
```
$ ivpm update
```

Variable Expansion Not Working

Problem: ${VAR} appears literally

Cause: Variable not defined or wrong order

Solutions:

# Define variables in dependency order
env:
  - name: BASE_DIR
    value: "/opt/base"

  - name: SUB_DIR
    value: "${BASE_DIR}/sub"  # Now BASE_DIR exists

Virtual Environment Issues

Venv Corrupted

Problem: Virtual environment not working

Cause: Corruption, version mismatch, or incomplete installation

Solutions:

# Remove and recreate
$ rm -rf packages/python
$ ivpm update

Wrong Python Version

Problem: Virtual environment uses wrong Python version

Cause: Created with different Python

Solutions:

$ rm -rf packages/python
$ python3.10 -m ivpm update  # Use specific version

Activate Not Working

Problem: ivpm activate fails or doesn’t change environment

Cause: Shell issues or venv not created

Solutions:

Check venv exists:
```
$ ls packages/python/bin/activate
```
Try direct activation:
```
$ source packages/python/bin/activate
```
Recreate venv:
```
$ rm -rf packages/python
$ ivpm update
```

Diagnostic Tools

Enable Debug Logging

Get detailed information about what IVPM is doing:

$ ivpm --log-level DEBUG update

Levels:

NONE - No logging (default)
WARN - Warnings only
INFO - Informational messages
DEBUG - Detailed debug information

Check IVPM Version

$ ivpm --version
$ python3 -m pip show ivpm

List Installed Packages

$ ivpm activate -c "pip list"
$ ivpm activate -c "pip list --format=json"

Check Dependency Tree

$ ivpm activate -c "pip show package-name"
$ ivpm activate -c "pipdeptree"  # If installed

Verify ivpm.yaml Syntax

$ python3 -c "import yaml; yaml.safe_load(open('ivpm.yaml'))"

Check Git Package Status

$ ivpm status  # All Git packages
$ cd packages/package-name && git status  # Specific package

Test Cache

$ ivpm cache info
$ ivpm cache info --verbose
$ ls -la $IVPM_CACHE

Common Error Messages

“Missing ‘package’ section YAML file”

Cause: Invalid or empty ivpm.yaml

Solution: Ensure ivpm.yaml has a package section:

package:
  name: my-project

“Dep-set X is not present in project Y”

Cause: Requested dependency set doesn’t exist

Solution: Check spelling and definition:

$ cat ivpm.yaml  # Verify dep-sets
$ ivpm update -d default-dev  # Use existing set

“No such file or directory: ivpm.yaml”

Cause: Not in project root or file doesn’t exist

Solution:

$ ls ivpm.yaml  # Check existence
$ cd /path/to/project  # Navigate to project root
$ ivpm init my-project  # Create if missing

“Git command failed”

Cause: Git clone/fetch/merge failed

Solutions:

Check network connectivity
Verify repository URL
Try anonymous mode (-a)
Check firewall/proxy settings

“Cannot determine source type from url”

Cause: URL doesn’t match known patterns

Solution: Explicitly specify src:

- name: package
  url: https://unusual-url.com/package
  src: http  # or git, file, etc.

Getting Help

Check Documentation

$ ivpm --help
$ ivpm <command> --help

Online Resources:

Documentation: https://fvutils.github.io/ivpm
GitHub: https://github.com/fvutils/ivpm
Issues: https://github.com/fvutils/ivpm/issues

Report a Bug

When reporting bugs, include:

IVPM version: ivpm --version
Python version: python3 --version
Operating system: uname -a
Command that failed
Full error message
Debug output: ivpm --log-level DEBUG <command>

Example bug report:

**IVPM Version:** 0.15.0
**Python:** 3.10.12
**OS:** Ubuntu 22.04
**Command:** ivpm update -d default-dev
**Error:** Git clone failed for package xyz
**Debug output:**
[Attach debug log]

Ask for Help

GitHub Issues: https://github.com/fvutils/ivpm/issues
Include minimal reproducible example
Share your ivpm.yaml (redact sensitive info)
Provide debug output

Prevention Tips

Version control ivpm.yaml - Track changes
Use .gitignore - Don’t commit packages/
Document custom setup - README for team members
Test before committing - ivpm update && pytest
Keep IVPM updated - pip install --upgrade ivpm
Use virtual environments - Isolate projects
Regular cache cleanup - ivpm cache clean
Check status regularly - ivpm status
Backup configurations - Copy ivpm.yaml
Read error messages carefully - They usually explain the issue

Troubleshooting

Common Issues and Solutions

Installation Issues

IVPM Command Not Found

Python Version Mismatch

Update Issues

SSH Authentication Failed

Package Already Exists

Git Clone Failed

Dependency Not Found

Python Package Issues

Module Not Found

Editable Install Not Working

Version Conflict

Native Extension Build Failed

Cache Issues

Cache Not Working

Broken Symlinks

Cache Permission Denied

Git Issues

Detached HEAD State

Merge Conflicts

Submodule Not Initialized

Cannot Push Changes

Environment Issues

Variables Not Set

Variable Expansion Not Working

Virtual Environment Issues

Venv Corrupted

Wrong Python Version

Activate Not Working

Diagnostic Tools

Enable Debug Logging

Check IVPM Version

List Installed Packages

Check Dependency Tree

Verify ivpm.yaml Syntax

Check Git Package Status

Test Cache

Common Error Messages

“Missing ‘package’ section YAML file”

“Dep-set X is not present in project Y”

“No such file or directory: ivpm.yaml”

“Git command failed”

“Cannot determine source type from url”

Getting Help

Check Documentation

Report a Bug

Ask for Help

Prevention Tips

See Also