Troubleshooting

This guide helps you resolve common issues when using YouTrack CLI.

Installation Issues

Command Not Found

Problem: yt: command not found after installation.

Solutions:

  1. Check if installation was successful:

    pip list | grep youtrack-cli

  2. Verify PATH configuration:

    # Check where pip installed the package
pip show -f youtrack-cli

# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

  3. Use full path temporarily:

    python -m youtrack_cli --help

Python Version Issues

Problem: Installation fails with Python version errors.

Solution: YouTrack CLI requires Python 3.9 or higher.

# Check Python version
python --version

# If using multiple Python versions
python3.9 -m pip install youtrack-cli
python3.9 -m youtrack_cli --help

Virtual Environment Issues

Problem: Package not found after installing in virtual environment.

Solution:

# Activate virtual environment first
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# Then install
pip install youtrack-cli

# Verify installation
yt --help

Permission Issues

Problem: Permission denied during installation.

Solutions:

  1. Install for current user only:

    pip install --user youtrack-cli

  2. Use virtual environment (recommended):

    python -m venv youtrack-env
source youtrack-env/bin/activate  # Linux/macOS
pip install youtrack-cli

  3. Use uv (fastest and recommended):

    # Install uv first (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install YouTrack CLI using uv
uv tool install youtrack-cli

# Or for development
git clone https://github.com/ryancheley/yt-cli.git
cd yt-cli
uv sync --dev
uv pip install -e .

Dependency Issues

Problem: CLI fails to run due to missing dependencies (e.g., ModuleNotFoundError: No module named 'click').

Solutions:

  1. Verify complete installation:

    # Check if all dependencies are installed
pip list | grep -E "(click|rich|textual|pydantic|httpx)"

  2. Reinstall with all dependencies:

    pip uninstall youtrack-cli
pip install --upgrade youtrack-cli

  3. Use uv for reliable dependency management:

    uv tool install youtrack-cli --force

  4. Development installation:

    git clone https://github.com/ryancheley/yt-cli.git
cd yt-cli
uv sync --dev
uv pip install -e .
yt --version  # Should work without errors

Authentication Issues

Login Failed

Problem: yt auth login fails with authentication error.

Common Causes & Solutions:

  1. Wrong YouTrack URL:

    # Ensure URL includes protocol and correct domain
# ✅ Correct:
https://yourcompany.youtrack.cloud

# ❌ Wrong:
yourcompany.youtrack.cloud
www.yourcompany.youtrack.cloud

  2. Invalid credentials:

    • Check username/password in YouTrack web interface

    • Try logging in via browser first

    • Reset password if necessary

  3. Network connectivity:

    # Test connection
curl https://yourcompany.youtrack.cloud/api/admin/projects

# Check proxy settings if behind corporate firewall

API Token Issues

Problem: API token authentication fails.

Solutions:

  1. Generate new token:

    • Go to YouTrack → Profile → Account Security → API Tokens

    • Create new token with appropriate permissions

    • Copy the full token value

  2. Verify token format:

    # Tokens should start with 'perm:'
# ✅ Correct format:
perm:cm9vdC5yb290.UGVybWlzc2lvbnM=.1234567890abcdef

# ❌ Wrong: Missing 'perm:' prefix

  3. Test token manually:

    curl -H "Authorization: Bearer perm:your-token-here" \
     https://yourcompany.youtrack.cloud/api/admin/projects

Configuration File Issues

Problem: Configuration not found or invalid.

Solutions:

  1. Check configuration file location:

    yt config list --show-file

  2. Verify file permissions:

    # Configuration should be readable
ls -la ~/.config/youtrack-cli/.env
chmod 600 ~/.config/youtrack-cli/.env

  3. Validate configuration format:

    # .env file format (NOT YAML):
YOUTRACK_BASE_URL=https://yourcompany.youtrack.cloud
YOUTRACK_TOKEN=perm:your-token-here
YOUTRACK_USERNAME=your-username

SSL Certificate Issues

Problem: SSL certificate verification fails.

Solutions:

  1. Update certificates:

    # Linux
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

  2. Temporary workaround (not recommended for production):

    export PYTHONHTTPSVERIFY=0
yt --help

Command Execution Issues

Permission Denied

Problem: Permission denied when running yt commands.

Solutions:

  1. Check YouTrack permissions:

    • Verify your user has appropriate permissions in YouTrack

    • Contact YouTrack admin to check user roles

  2. Token permissions:

    • Recreate API token with correct permissions

    • Ensure token has project access rights

Invalid Project or Issue ID

Problem: Project not found or Issue not found errors.

Solutions:

  1. Verify project exists:

    yt projects list

  2. Check project key format:

    # ✅ Correct format:
yt issues create WEB-FRONTEND "Issue title"

# ❌ Wrong format:
yt issues create "Web Frontend" "Issue title"

  3. Verify issue ID format:

    # ✅ Correct:
yt issues update WEB-123 --state "In Progress"

# ❌ Wrong:
yt issues update 123 --state "In Progress"

Network and Connectivity Issues

Connection Timeout

Problem: Commands hang or timeout.

Solutions:

  1. Check network connectivity:

    ping yourcompany.youtrack.cloud

  2. Test YouTrack API directly:

    curl -I https://yourcompany.youtrack.cloud/api/admin/projects

  3. Corporate proxy configuration:

    # Set proxy environment variables
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.company.com

Rate Limiting

Problem: Too many requests errors.

Solutions:

  1. Add delays between commands:

    # Use in scripts
yt issues list --limit 10
sleep 1
yt issues list --limit 10 --offset 10

  2. Reduce request frequency:

    • Use --limit options to fetch smaller batches

    • Implement exponential backoff in scripts

Data and Output Issues

Empty Results

Problem: Commands return no results when data should exist.

Solutions:

  1. Check user permissions:

    # You might not have access to see certain projects/issues
yt projects list  # See what projects you can access

  2. Verify search parameters:

    # Start with broader searches
yt issues list --limit 5
yt issues search "created: today"

  3. Check project context:

    # Specify project explicitly
yt issues list --project PROJECT-KEY

Output Formatting Issues

Problem: Garbled or poorly formatted output.

Solutions:

  1. Check terminal encoding:

    export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

  2. Try different output formats:

    yt issues list --format json
yt issues list --format table

  3. Disable colors if needed:

    yt issues list --no-color

Command-Specific Issues

Issue Creation Fails

Problem: yt issues create fails with validation errors.

Common Issues:

  1. Missing required fields:

    # ✅ Include all required fields:
yt issues create PROJECT-KEY "Issue summary" \
  --description "Detailed description" \
  --type "Bug"

  2. Invalid field values:

    # Check valid values first:
yt projects list  # For project keys
yt issues list --limit 1  # To see valid field examples

  3. Special characters in summary:

    # Quote strings with special characters:
yt issues create PROJECT-KEY "Fix: API returns 500 error"

Time Tracking Issues

Problem: Time logging fails or shows unexpected format.

Solutions:

  1. Use correct time format:

    # ✅ Correct formats:
yt time log ISSUE-123 "2h 30m"
yt time log ISSUE-123 "4h"
yt time log ISSUE-123 "90m"

# ❌ Wrong formats:
yt time log ISSUE-123 "2.5h"
yt time log ISSUE-123 "2:30"

  2. Check permissions:

    • Verify you can edit the issue

    • Ensure time tracking is enabled for the project

Getting Help

Debugging and Logging

YouTrack CLI includes a comprehensive logging system built with structured logging to help troubleshoot issues.

Quick Debugging

For immediate troubleshooting, use these flags:

# Debug mode shows detailed HTTP requests, responses, and internal operations
yt --debug issues list
yt --debug auth login

# Verbose mode shows progress information and warnings
yt --verbose projects list
yt --verbose issues create PROJECT-KEY "New issue"

# Set specific log levels
yt --log-level ERROR issues list
yt --log-level DEBUG auth login

Comprehensive Logging Documentation

For detailed information about the logging system, including:

  • Advanced log level control

  • File-based logging with rotation

  • Sensitive data masking

  • API call tracking

  • Performance monitoring

  • Log aggregation for external tools

See the complete Logging and Debugging guide.

Enhanced Error Messages

YouTrack CLI provides user-friendly error messages with actionable suggestions:

# Example error with suggestion
$ yt issues list --project INVALID-PROJECT
Error: Project 'INVALID-PROJECT' not found
Suggestion: Check if the project exists and you have access to it

Error Categories

The CLI categorizes errors to provide better context:

  • AuthenticationError: Login or token issues

  • ConnectionError: Network or server connectivity problems

  • NotFoundError: Missing resources (projects, issues, etc.)

  • PermissionError: Access rights issues

  • ValidationError: Invalid input or parameters

  • RateLimitError: Too many requests (includes retry suggestions)

Automatic Retry Logic

Network requests include automatic retry with exponential backoff:

# The CLI automatically retries failed requests up to 3 times
# You'll see warnings like:
# "Request timed out, retrying in 2s..."
# "Connection failed, retrying in 4s..."

Log Files

Check log files for detailed error information:

# Default log location (varies by OS)
# Linux/macOS:
tail -f ~/.local/share/youtrack-cli/logs/youtrack-cli.log

# Windows:
type %APPDATA%\youtrack-cli\logs\youtrack-cli.log

Command Help

Every command has built-in help:

# General help
yt --help

# Command group help
yt issues --help
yt projects --help

# Specific command help
yt issues create --help
yt time log --help

Testing Configuration

Verify your setup is working:

# Test authentication
yt auth login --test

# Test basic operations
yt projects list --limit 1
yt issues list --limit 1

Common Error Messages

“Module not found”

Error: ModuleNotFoundError: No module named 'youtrack_cli'

Solution: Reinstall the package:

pip uninstall youtrack-cli
pip install youtrack-cli

“Invalid token format”

Error: AuthenticationError: Invalid token format

Solution: Ensure token includes perm: prefix:

# Correct format
YOUTRACK_TOKEN=perm:cm9vdC5yb290.UGVybWlzc2lvbnM=.1234567890abcdef

“Connection refused”

Error: ConnectionError: Connection refused

Solutions:

  1. Check YouTrack URL is correct and accessible

  2. Verify network connectivity

  3. Check if YouTrack service is running

“Project not found”

Error: NotFoundError: Project 'PROJECT-KEY' not found

Solutions:

  1. List available projects: yt projects list

  2. Check project key spelling and case

  3. Verify you have access to the project

“Unauthorized”

Error: AuthenticationError: 401 Unauthorized

Solutions:

  1. Verify credentials are correct

  2. Check API token permissions

  3. Test login in YouTrack web interface

Command Syntax Errors

This section addresses common command syntax errors and their solutions.

Articles Command Issues

Problem: yt articles create "Test Article" --project-id TEST fails with content required error.

Solution: Either --content or --file is required along with --project-id:

# ✅ Correct with inline content:
yt articles create "Test Article" --content "Your content here" --project-id TEST

# ✅ Correct with file:
yt articles create "Test Article" --file ./content.md --project-id TEST

# ❌ Wrong - missing content:
yt articles create "Test Article" --project-id TEST

Issues Command Issues

Problem: yt issues assign DEMO-20 --assignee admin fails with “no such option” error.

Solution: Use positional arguments, not flags:

# ✅ Correct:
yt issues assign DEMO-20 admin

# ❌ Wrong:
yt issues assign DEMO-20 --assignee admin

Problem: yt issues attach 3-19 fails with “Missing command” error.

Solution: Attach requires a subcommand:

# ✅ Correct:
yt issues attach list ISSUE-123
yt issues attach upload ISSUE-123 /path/to/file.txt

# ❌ Wrong:
yt issues attach ISSUE-123

Problem: yt issues comments add DEMO-20 --text "comment" fails with “no such option” error.

Solution: Use positional arguments for comment text:

# ✅ Correct:
yt issues comments add DEMO-20 "Your comment here"

# ❌ Wrong:
yt issues comments add DEMO-20 --text "comment"

Problem: yt issues comments create DEMO-20 fails with “no such command” error.

Solution: Use add instead of create for comments:

# ✅ Correct:
yt issues comments add DEMO-20 "Your comment"

# ❌ Wrong:
yt issues comments create DEMO-20

Projects Command Issues

Problem: yt projects create "CLI-TEST" fails with missing arguments error.

Solution: Both NAME and SHORT_NAME are required positional arguments:

# ✅ Correct:
yt projects create "CLI Testing Project" CLI-TEST

# ❌ Wrong:
yt projects create "CLI-TEST"

Reports Command Issues

Problem: yt reports burndown --project DEMO fails with “no such option” error.

Solution: Use project ID as positional argument:

# ✅ Correct:
yt reports burndown DEMO

# ❌ Wrong:
yt reports burndown --project DEMO

Users Command Issues

Problem: yt users create testuser --email "test@example.com" fails with missing arguments error.

Solution: All user details are positional arguments:

# ✅ Correct:
yt users create testuser "Test User" "test@example.com"

# ❌ Wrong:
yt users create testuser --email "test@example.com"

Problem: yt users permissions admin fails with missing required option error.

Solution: The --action parameter is required:

# ✅ Correct:
yt users permissions admin --action add_to_group --group-id developers

# ❌ Wrong:
yt users permissions admin

Version Command Issues

Problem: yt version fails with “no such command” error.

Solution: Use --version flag instead:

# ✅ Correct:
yt --version

# ❌ Wrong:
yt version

Interactive Command Behavior

Several commands have interactive behavior that prompts for additional information:

Setup Command:

yt setup launches an interactive wizard for initial configuration.

Authentication Commands:

  • yt auth login - Interactive authentication setup

  • yt auth token update - Interactive token updating

Tutorial Command:

yt tutorial run provides interactive learning modules.

User Creation:

yt users create will prompt for password interactively for security.

Project Creation:

yt projects create will prompt for project leader if not specified with --leader.

Release and Development Issues

Release Creation Problems

Problem: just release command fails during pre-flight checks.

Common Issues and Solutions:

Not on main branch:
# Check current branch
git branch --show-current

# Switch to main
git checkout main
Working directory not clean:
# Check what files are uncommitted
git status --short

# Commit changes or stash them
git add . && git commit -m "Pre-release cleanup"
# or
git stash
Local branch not up-to-date:
# Pull latest changes
git pull origin main
Quality checks failing:
# Run checks individually to identify issues
just lint          # Fix linting issues
just format        # Fix formatting
just typecheck     # Fix type issues
just test         # Fix failing tests
just security     # Fix security issues

Problem: Version validation fails.

Solutions:

Invalid version format:
# ✅ Correct semantic versioning:
just release 0.2.3
just release 1.0.0

# ❌ Wrong formats:
just release 0.2    # Missing patch version
just release v0.2.3 # Don't include 'v' prefix
just release 0.2.3-beta # Pre-release versions not supported
Version already exists:
# Check existing tags
git tag -l | sort -V

# Use next appropriate version
just release 0.2.4
Not a proper version increment:
# Check current version
just release-status

# Use proper increment (patch, minor, or major)
just release-check 0.2.3  # Validate before running

GitHub Actions Failures

Problem: Release workflow fails after tag is pushed.

Diagnostic Steps:

  1. Check workflow status:

    # View recent workflow runs
gh run list --limit 5

# View specific run details
gh run view <run-id>

# View failed job logs
gh run view <run-id> --log-failed

  2. Common failure causes:

    Tests failing in CI:

    • Tests may pass locally but fail in CI due to environment differences

    • Check the test logs in GitHub Actions

    • Run tests locally with exact CI conditions

    Build failures:

    • Missing dependencies in CI environment

    • Check pyproject.toml for correct dependency versions

    PyPI publishing failures:

    • API token permissions or expiration

    • Package name conflicts

    • Missing repository secrets (PYPI_TOKEN)

Problem: Package published to Test PyPI but not main PyPI.

Solutions:

  1. Check Test PyPI results:

    # View Test PyPI package
# https://test.pypi.org/project/youtrack-cli/

  2. Manual PyPI troubleshooting:

    # Check if package exists on main PyPI
pip index versions youtrack-cli

# Test installation from Test PyPI
pip install -i https://test.pypi.org/simple/ youtrack-cli

Release Rollback Issues

Problem: Need to rollback a failed release.

Solutions:

  1. Before PyPI publication (tag exists but package not published):

    # Use automated rollback
just rollback-release 0.2.3

  2. After PyPI publication (package already live):

    # PyPI doesn't allow deletion - create new version
just release-check 0.2.4  # Validate next version
just release 0.2.4        # Create hotfix release

  3. Manual rollback steps (if automated rollback fails):

    # Delete remote tag
git push origin :refs/tags/v0.2.3

# Delete local tag
git tag -d v0.2.3

# Revert version commit (if it's the last commit)
git reset --hard HEAD~1
git push --force-with-lease origin main

Development Environment Issues

Problem: just command not found.

Solutions:

  1. Install just:

    # macOS
brew install just

# Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/bin

# Windows (using cargo)
cargo install just

  2. Alternative - use make:

    # Manual commands instead of just recipes
uv sync --dev
uv run pytest
uv run ruff check

Problem: Pre-commit hooks failing.

Solutions:

  1. Install pre-commit hooks:

    uv run pre-commit install

  2. Run hooks manually:

    # Run all hooks
uv run pre-commit run --all-files

# Run specific hook
uv run pre-commit run ruff

  3. Skip hooks temporarily (not recommended):

    git commit --no-verify -m "message"

Problem: Type checking failures with ty.

Solutions:

  1. Install correct type checker:

    # Project uses 'ty', not 'mypy'
uv sync --dev
uv run ty check

  2. Common type issues:

    # Ignore specific issues during development
uv run ty check --ignore call-non-callable --ignore unresolved-attribute

Version Management Issues

Problem: Version mismatch between files.

Solutions:

  1. Check version consistency:

    # Check pyproject.toml version
grep '^version =' pyproject.toml

# Check package version
python -c "import youtrack_cli; print(youtrack_cli.__version__)"

  2. Fix version inconsistencies:

    # Use justfile version bump
just version-bump 0.2.3

# This updates pyproject.toml correctly

Problem: uv.lock file out of sync.

Solutions:

# Update lock file
uv sync

# Or regenerate completely
rm uv.lock
uv sync --dev

CI/CD Integration Issues

Problem: GitHub Actions workflow not triggering.

Solutions:

  1. Check workflow triggers:

    # Ensure tag was pushed correctly
git ls-remote --tags origin

# Check if tag follows correct format
git tag -l | grep "^v[0-9]"

  2. Verify workflow files:

    # Check workflow syntax
cat .github/workflows/release.yml

# Test with GitHub CLI
gh workflow list

Problem: Secrets not available in workflow.

Solutions:

  1. Check repository secrets:

    • Go to GitHub repo → Settings → Secrets and variables → Actions

    • Ensure PYPI_TOKEN exists and is valid

    • Verify environment protection rules

  2. Test secrets locally (for debugging):

    # Test PyPI token manually
twine check dist/*
twine upload --repository testpypi dist/*

Still Need Help?

If this guide doesn’t resolve your issue:

  1. Check existing issues: GitHub Issues

  2. Create new issue: Include error messages, command used, and system info

  3. Join discussions: GitHub Discussions

When reporting issues, include:

# System information
yt --version
python --version
pip list | grep youtrack-cli

# Development environment info (if relevant)
just --version
uv --version
git --version

# Error output with debug flag
yt --debug [your-command-here]

# Release-specific debugging
just release-status
git status
git log --oneline -5