Troubleshooting

This guide covers common issues you might encounter when installing, configuring, or using python-gitea, and how to resolve them.

Setup Issues

Virtual Environment Issues

Problem: Packages can't be found or dependencies conflict.

Solutions:

Create a fresh virtual environment with uv (--clear replaces the existing one and works on all platforms, removing the need for rm -rf .venv):
```
uv venv --clear --python 3.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```
Install the project and its development dependencies:
```
uv sync --group dev
```

Verify the installation:

python -c "import gitea; print(gitea.__version__)"

If you installed with pip instead, upgrade it first:
```
pip install --upgrade pip uv
```

For details, see the Installation Guide.

Python Version Mismatch

Problem: uv venv fails or tests don't run with the wrong Python version.

Solutions:

Check your Python version:
```
python --version
```
python-gitea requires Python 3.12 or later and is built and tested against Python 3.12-3.14.

Create the virtual environment with a supported version:

uv venv --python 3.12  # 3.12, 3.13, or 3.14
source .venv/bin/activate

Pre-commit Hooks Not Installed

Problem: Formatting and linting hooks don't run when you commit.

Solutions:

Ensure you're in the project root directory (must be a git repository).
Install the hooks with prek:
```
uv run prek install
```
Run all hooks manually:
```
uv run prek run --all-files
```
Check which hooks are configured in .pre-commit-config.yaml.

Pull request titles are validated in CI (.github/workflows/semantic_pull_request.yml), not locally.

Configuration Issues

Account Not Found

Problem: A command fails with Account 'name' does not exist in the configuration.

Solutions:

List your configured accounts:
```
gitea-cli config list
```

Add the missing account:

gitea-cli config add --name name --token YOUR_API_TOKEN --base-url https://gitea.example.com

Pass the account explicitly with --account-name name, or use a token and base URL directly.

See Configuration for the full account workflow.

No Default Account Available

Problem: A command fails with No default account available for authentication.

Solutions:

Set a default account:

gitea-cli config update --name name --default

Or pass credentials on the command line:

gitea-cli issue list --owner my-org --repository my-repo --token YOUR_API_TOKEN --base-url https://gitea.example.com

The first account added becomes the default automatically.

Duplicate Account

Problem: Adding an account fails with Account 'name' already exists in the configuration.

Solutions:

Update the existing account instead:

gitea-cli config update --name name --token NEW_TOKEN

Or delete it first if you want to recreate it. Include the original --base-url so the account is recreated against the same Gitea instance:

gitea-cli config delete --name name
gitea-cli config add --name name --token YOUR_API_TOKEN --base-url https://gitea.example.com

Invalid Configuration File

Problem: Loading the config file fails with Invalid configuration format.

Solutions:

Check the config file for syntax errors and that the account fields (name, token, base_url) are valid YAML.
The default location is platform-dependent (see Configuration).

Remove or rename the broken file and reconfigure:

gitea-cli config add --name name --token YOUR_API_TOKEN --base-url https://gitea.example.com

API Issues

Authentication Failed (401)

Problem: Requests return 401 Unauthorized.

Solutions:

Verify the token is valid for the target Gitea instance.
Check the base URL points at your Gitea instance (not the repo web UI).
Confirm the token has the required scopes for the operation.

Resource Not Found (404)

Problem: Requests return 404 Not Found.

Solutions:

Verify --owner/--repository point at an existing repository.
Check issue/PR indices, label and milestone IDs, and project/column IDs exist.
Confirm the authenticated account has access to the resource.

JSON Parsing Errors

Problem: Logs show Failed to parse JSON response and methods return empty data.

Solutions:

Confirm the base URL points at a Gitea API endpoint, e.g. https://gitea.example.com (the client appends /api/v1).
Test the endpoint with a manual request, for example by calling https://gitea.example.com/api/v1/user with your token in the authorization header.

Testing Issues

Pytest Fails to Collect Tests

Problem: pytest returns "no tests collected" or import errors.

Solutions:

Verify test file naming: pytest discovers test_*.py and *_test.py by default.
Verify test function naming: names must start with test (e.g. test_list_issues or test_list); this project uses test_-prefixed names.
Run from the project root:
```
uv run pytest -vv
```
Check test discovery:
```
uv run pytest --collect-only
```

Import Errors in Tests

Problem: Tests can't import gitea modules.

Solutions:

Ensure development dependencies are installed:
```
uv sync --group dev
```
Verify the src layout is correct (package lives in src/gitea/) and that [tool.pytest.ini_options].pythonpath includes src.
Run from the project root directory.

Coverage Report Issues

Problem: Coverage report shows 0% or missing files.

Solutions:

Run pytest with coverage:
```
uv run pytest --cov-report=html
```
Coverage is configured in pyproject.toml under [tool.coverage]; the default addopts already enables coverage on src.
Verify test files import from the src/ layout correctly.

Pre-commit Hook Issues

Hooks Running Too Slowly

Problem: Pre-commit takes a very long time or times out.

Solutions:

Check which hooks are slow:
```
uv run prek run --all-files --verbose
```

Run specific hooks:

uv run prek run ruff --all-files
uv run prek run prettier --all-files

Formatting Changes After Commit

Problem: Pre-commit auto-fixes files, but you didn't expect it.

Solutions:

This is normal behavior - review the changes.
Stage the new changes and commit again:
```
git add .
git commit -m "your message"
```
Modify the tool settings if the behavior is unwanted (e.g. in .pre-commit-config.yaml or pyproject.toml).

"Unstaged Changes" After Running Hooks

Problem: Pre-commit modified files but they're not staged.

Solutions:

This is expected - review the changes:
```
git diff
```
Stage and commit:
```
git add .
git commit -m "your message"
```

Getting Help

If you encounter issues not listed here:

Check existing issues: Search GitHub Issues for your problem.

Review logs carefully: Run with verbose logging to see request details:

gitea-cli --verbose DEBUG issue list --owner my-org --repository my-repo

Try a minimal reproduction: Isolate the problem to a single command.
Ask for help: Open an issue with:
Your environment (Python version, OS)
Steps to reproduce
Full error message/logs
What you've already tried