Troubleshooting

This guide covers common issues you might encounter when using releasio and how to resolve them.

Configuration Errors

Configuration file not found

Error: ConfigNotFoundError: Could not find pyproject.toml

Cause: releasio requires a pyproject.toml file with project metadata.

Solution:

1. Ensure you're running releasio from your project root directory
2. Verify pyproject.toml exists and contains a [project] section:

[project]
name = "your-package"
version = "1.0.0"

Invalid configuration values

Error: ConfigValidationError: Invalid configuration

Cause: Configuration values don't match expected types or constraints.

Solution:

1. Check for typos in configuration keys (releasio uses extra = "forbid" to catch these)
2. Verify all paths are valid
3. Ensure version patterns follow semantic versioning

# Correct
[tool.releasio.version]
tag_prefix = "v"

# Wrong - 'prefix' instead of 'tag_prefix'
[tool.releasio.version]
prefix = "v"  # This will error

---

Git Errors

Not a git repository

Error: NotARepositoryError: Not a git repository

Cause: The current directory is not initialized as a git repository.

Solution:

# Initialize git repository
git init

# Or navigate to the correct directory
cd /path/to/your/project

Dirty repository

Error: DirtyRepositoryError: Repository has uncommitted changes

Cause: You have uncommitted changes and allow_dirty = false in configuration.

Solution:

Commit your changesAllow dirty working tree

git add .
git commit -m "chore: save work in progress"

[tool.releasio]
allow_dirty = true

Tag already exists

Error: TagExistsError: Tag 'v1.0.0' already exists

Cause: You're trying to create a release with a version that's already tagged.

Solution:

1. Check existing tags:

   git tag -l
   

2. If the tag was created by mistake, delete it:

   git tag -d v1.0.0
   git push origin :refs/tags/v1.0.0  # Remove from remote
   

3. Or bump the version manually:

   releasio update --execute --bump minor
   

---

Version Errors

Invalid version format

Error: InvalidVersionError: Invalid version: '1.0' (must follow PEP 440)

Cause: The version string doesn't follow PEP 440 format.

Solution:

Use a valid semantic version format:

# Valid versions
version = "1.0.0"
version = "2.1.0a1"      # Alpha pre-release
version = "2.1.0b2"      # Beta pre-release
version = "2.1.0rc1"     # Release candidate
version = "1.0.0.post1"  # Post-release

# Invalid versions
version = "1.0"          # Missing patch
version = "v1.0.0"       # No 'v' prefix in version string
version = "1.0.0-beta"   # Use PEP 440 format: 1.0.0b1

Version not found

Error: VersionNotFoundError: Could not find version in project files

Cause: releasio couldn't locate the version in your project.

Solution:

Ensure version is defined in pyproject.toml:

[project]
name = "your-package"
version = "1.0.0"  # Required

Or configure custom version file locations:

[tool.releasio.version]
files = ["src/mypackage/__init__.py"]

---

GitHub Errors

Authentication failed

Error: AuthenticationError: GitHub authentication failed

Cause: Invalid or missing GitHub token.

Solution:

GitHub ActionsLocal CLI

Ensure you're passing the token to the action:

- uses: mikeleppane/releasio-action@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

Set the GITHUB_TOKEN environment variable:

export GITHUB_TOKEN=ghp_your_token_here
releasio release-pr --execute

Rate limit exceeded

Error: RateLimitError: API rate limit exceeded. Resets at 2024-01-15T10:30:00Z

Cause: Too many GitHub API requests.

Solution:

1. Wait for the rate limit to reset (shown in error message)
2. Use a token with higher limits:
3. Unauthenticated: 60 requests/hour
4. Authenticated: 5,000 requests/hour
5. Reduce API calls by running releasio less frequently

---

Publishing Errors

Build failed

Error: BuildError: Failed to build package

Cause: The package build process failed.

Solution:

1. Test the build locally:

   # With uv
   uv build
   
   # With pip
   pip install build
   python -m build
   

2. Check for missing files in your pyproject.toml:

   [build-system]
   requires = ["hatchling"]
   build-backend = "hatchling.build"
   
   [tool.hatch.build.targets.wheel]
   packages = ["src/your_package"]
   

3. Verify MANIFEST.in includes all necessary files

Already published

Error: AlreadyPublishedError: mypackage 1.0.0 is already published

Cause: This version already exists on PyPI.

Solution:

PyPI doesn't allow overwriting published versions. You must:

1. Bump the version:

   releasio update --execute --bump patch
   

2. Or use a pre-release suffix:

   releasio update --execute --pre-release rc1
   

Upload failed

Error: UploadError: Failed to upload to PyPI

Cause: Various issues with PyPI upload.

Solution:

1. Check your credentials:
2. For Trusted Publishing, ensure your GitHub workflow is configured correctly

3. For token auth, verify your PYPI_TOKEN is valid

4. Verify package name availability:

5. Search PyPI to ensure the name isn't taken

6. Check network connectivity:

   curl -I https://upload.pypi.org/legacy/
   

---

Changelog Errors

git-cliff not found

Error: ChangelogError: git-cliff not found, using native fallback

Cause: git-cliff is not installed (this is a warning, not an error).

Solution:

Install git-cliff (recommended)Use native changelog

# macOS
brew install git-cliff

# Linux
cargo install git-cliff

# Or use pre-built binaries from GitHub releases

releasio automatically falls back to native changelog generation. No action needed.

Empty changelog

Cause: No conventional commits found since the last release.

Solution:

1. Ensure you're using conventional commits:

   git log --oneline -10  # Check recent commits
   

2. Valid conventional commit formats:

   feat: add new feature
   fix: resolve bug
   docs: update readme
   chore: update dependencies
   

3. Check your commit type configuration:

   [tool.releasio.commits]
   types_minor = ["feat"]
   types_patch = ["fix", "perf", "docs", "refactor"]
   

---

Common Issues

No version bump detected

Cause: Commits since last tag don't match any configured bump types.

Solution:

1. Check commits since last tag:

   releasio check
   

2. Ensure commits follow conventional format:

   feat: ...   # Minor bump
   fix: ...    # Patch bump
   feat!: ...  # Major bump (breaking change)
   

3. Verify configuration:

   [tool.releasio.commits]
   types_minor = ["feat"]
   types_patch = ["fix", "perf", "docs", "refactor", "style", "test", "build", "ci"]
   

Pre-commit hooks fail

Cause: Code style or type errors before commit.

Solution:

1. Run formatters:

   ruff format .
   ruff check --fix .
   

2. Fix type errors:

   mypy src/
   

3. Skip hooks temporarily (not recommended):

   git commit --no-verify -m "feat: emergency fix"
   

---

Getting Help

If you can't resolve your issue:

1. Check existing issues: GitHub Issues
2. Search discussions: GitHub Discussions
3. Open a new issue with:
4. releasio version (releasio --version)
5. Python version (python --version)
6. Full error message and stack trace
7. Your pyproject.toml configuration (remove sensitive data)
8. Steps to reproduce