Troubleshooting

Common issues and their solutions.

Project Detection

"No dependency information found"

# Error: No dependency information found. Generate a lock file (uv.lock, poetry.lock,
# Pipfile.lock, pylock.toml) or add pyproject.toml/requirements.txt

# Ensure you're in a Python project directory
ls pyproject.toml uv.lock poetry.lock pylock.toml requirements.txt

# Or specify the path explicitly
pysentry /path/to/python/project

Requirements.txt files not being detected

# Ensure requirements.txt exists
ls requirements.txt

# Specify path explicitly
pysentry /path/to/python/project

# Include additional requirements files
pysentry --requirements-files requirements-dev.txt requirements-test.txt

# Check if higher-priority files exist (they take precedence)
ls uv.lock poetry.lock Pipfile.lock pyproject.toml Pipfile requirements.txt

Resolver Issues

"No supported dependency resolver found"

# Error: No supported dependency resolver found. Please install uv or pip-tools.

# Install a supported resolver in your environment
pip install uv           # Recommended - fastest
pip install pip-tools    # Alternative

# Verify resolver is available
uv --version
pip-compile --version

# If using virtual environments, ensure resolver is installed there
source venv/bin/activate
pip install uv
pysentry /path/to/project

"uv resolver not available"

# Install uv
pip install uv

# Verify installation
which uv
uv --version

# Ensure it's in your PATH
export PATH="$PATH:$(python -m site --user-base)/bin"

"Failed to resolve requirements"

# Check your requirements.txt syntax
cat requirements.txt

# Try different resolver
pysentry --resolver pip-tools  # if uv fails
pysentry --resolver uv         # if pip-tools fails

# Ensure you're in correct environment
which python
which uv  # or which pip-compile

# Debug with verbose output
pysentry -vvv /path/to/project

Network Issues

"Failed to fetch vulnerability data"

# Check network connectivity to OSV API
curl -I https://api.osv.dev/v1

# Try with different or fewer sources
pysentry --sources pypi
pysentry --sources pypa,osv

Network timeout errors

PySentry includes automatic retry with exponential backoff. The default timeout is 120 seconds. For persistent timeouts:

# .pysentry.toml
[http]
timeout = 300           # 5 minute timeout (default: 120)
max_retries = 5         # More retry attempts (default: 3)
retry_max_backoff = 120 # Longer backoff delays (default: 60)

# Then run again
pysentry

Resolver timeout errors

If you see UvTimeout or PipToolsTimeout errors, the resolver is taking too long to resolve dependencies. This can happen with large dependency trees or slow network connections. Consider generating a lock file instead:

# Generate lock file with uv (faster than scanning requirements.txt)
uv lock

# Then scan the lock file
pysentry /path/to/project

Rate limiting (HTTP 429 errors)

PySentry handles rate limiting automatically. If rate limits persist:

# .pysentry.toml
[http]
max_retries = 5              # More attempts
retry_initial_backoff = 5    # Longer initial wait
retry_max_backoff = 300      # Up to 5 minute backoff

Performance Issues

Slow requirements.txt resolution

# Use faster uv resolver instead of pip-tools
pysentry --resolver uv

# Install uv for better performance (2-10x faster)
pip install uv

# Or use uvx for isolated execution
uvx pysentry-rs --resolver uv /path/to/project

General slow performance

# Clear all caches and retry
rm -rf ~/.cache/pysentry      # Linux
rm -rf ~/Library/Caches/pysentry  # macOS
pysentry

# Clear only resolution cache (if vulnerability cache is working)
rm -rf ~/.cache/pysentry/dependency-resolution/      # Linux
rm -rf ~/Library/Caches/pysentry/dependency-resolution/  # macOS
pysentry

# Clear resolution cache via CLI
pysentry --clear-resolution-cache

# Use verbose mode to identify bottlenecks
pysentry -vvv

# Disable caching to isolate issues
pysentry --no-cache

Cache Issues

Stale cache causing problems

# Clear stale resolution cache after environment changes
pysentry --clear-resolution-cache

# Disable resolution cache if causing issues
pysentry --no-resolution-cache

# Force fresh resolution (ignores cache)
pysentry --clear-resolution-cache --no-resolution-cache

Cache corruption

# Delete all caches and rebuild
rm -rf ~/.cache/pysentry/
pysentry /path/to/project

Extend cache TTL for stable environments

pysentry --resolution-cache-ttl 168  # 1 week

Check cache usage

# Verbose output shows cache hits/misses
pysentry -vv

Configuration Issues

Configuration file not being loaded

# Check configuration paths
pysentry config path

# Validate configuration
pysentry config validate

# Show effective configuration
pysentry config show

# Override configuration path
PYSENTRY_CONFIG=/path/to/.pysentry.toml pysentry

# Disable configuration files
PYSENTRY_NO_CONFIG=1 pysentry

Invalid configuration syntax

# Validate your configuration file
pysentry config validate

# Check TOML syntax
cat .pysentry.toml

Unknown Severity Vulnerabilities

What does "UNKNOWN" severity mean?

Some vulnerability advisories don't include CVSS scoring data, so PySentry can't determine their severity level. These are reported as UNKNOWN.

By default, unknown severity vulnerabilities cause a non-zero exit code (same as any other severity). To change this:

# Don't fail on unknown severity vulnerabilities
pysentry --no-fail-on-unknown

# Combine with fail-on to only fail on high+ but still report unknowns
pysentry --fail-on high --no-fail-on-unknown

Why are some vulnerabilities showing UNKNOWN?

This typically happens with:

• Newly published advisories that haven't been scored yet
• Advisories from sources that don't provide CVSS data (e.g., PyPI JSON API)
• Withdrawn or partially retracted advisories

Use --detailed to see more information about the vulnerability, including its source and any available references.

CI/CD Issues

GitHub Actions annotations not appearing

PySentry auto-detects GitHub Actions via the GITHUB_ACTIONS environment variable. If annotations aren't showing:

# Verify CI detection is not disabled
# Check your .pysentry.toml for no_ci_detect = true

# Run with verbose output to see CI detection
pysentry -vv

Disabling CI behavior

If CI auto-detection interferes with your workflow:

# Disable via CLI flag
pysentry --no-ci-detect

# Or via configuration
# .pysentry.toml
# [defaults]
# no_ci_detect = true

Feedback messages appearing in CI

PySentry automatically suppresses feedback and survey messages in detected CI environments. If they still appear, ensure the CI environment variable is set (e.g., GITHUB_ACTIONS, GITLAB_CI, CI).

Output Issues

No output displayed

# Check if quiet mode is enabled
pysentry  # Without -q flag

# Enable verbose output
pysentry -v

Output format issues

# Explicitly specify format
pysentry --format human
pysentry --format json --output results.json

Pre-commit Issues

Hook takes too long

# Use faster resolver and limit sources
repos:
  - repo: https://github.com/pysentry/pysentry-pre-commit
    rev: v0.4.3
    hooks:
      - id: pysentry
        args: ["--resolver", "uv", "--sources", "pypa"]

Resolver not found in pre-commit

# Update pre-commit environments
pre-commit clean
pre-commit install --install-hooks

Debug Commands

Check available resolvers

pysentry resolvers

Show configuration

pysentry config show

Validate configuration

pysentry config validate

Verbose debugging

# Warnings
pysentry -v

# Info (recommended for troubleshooting)
pysentry -vv

# Debug (detailed)
pysentry -vvv

# Trace (maximum verbosity)
pysentry -vvvv

Module-specific debugging

# Debug dependency resolution
RUST_LOG=pysentry::dependency=debug pysentry /path/to/project

# Debug parser selection
RUST_LOG=pysentry::parsers=debug pysentry /path/to/project

# Debug caching
RUST_LOG=pysentry::cache=debug pysentry /path/to/project

Getting Help

If these solutions don't resolve your issue:

1. Check existing issues: GitHub Issues
2. Open a new issue: Include verbose output (pysentry -vvv)
3. Join discussions: GitHub Discussions
4. Email support: [email protected]