# Troubleshooting Common Issues

This reference consolidates the most frequent problems users encounter while creating, installing, or publishing Python libraries. Use it when the quickstart or primary guidelines aren’t enough.

---

## 1. `ModuleNotFoundError` After Installation

This occurs when the package structure or naming is incorrect.

**Symptoms**
```text
ModuleNotFoundError: No module named 'my_utils'
```

**Checks & Fixes**
- ✅ Run `python scripts/validate_structure.py .` from library root. Fix any reported issues.
- ✅ Ensure `src/my_utils/__init__.py` exists (even if empty).
- ✅ Verify `pyproject.toml` `name` matches the folder (`my-utils` vs `my_utils`).
- ✅ Confirm you installed the correct package:
  ```bash
  uv add git+ssh://git@gitlab.com/synapsis/my-utils.git
  # or
  uv add my-utils  # PyPI
  ```
- ✅ In consumer project, run `uv lock --upgrade-package my-utils` to refresh.

If the import still fails, open a Python REPL and inspect `sys.path`:
```python
import sys
print(sys.path)
```
Look for the path pointing to your library’s site-packages.

---

## 2. Git Authentication Fails During Installation

**Symptoms**
```text
git+ssh://git@gitlab.com/synapsis/my-utils.git#egg=my-utils
Permission denied (publickey).
```

**Fixes**
- Run `ssh -T git@gitlab.com`.
- If you see `Permission denied (publickey)`, your SSH key isn’t registered.
- Generate a key:
  ```bash
  ssh-keygen -t ed25519 -C "your.email@example.com"
  eval "$(ssh-agent -s)"
  ssh-add ~/.ssh/id_ed25519
  cat ~/.ssh/id_ed25519.pub
  ```
- Add the `.pub` key to GitLab under **User Settings → SSH Keys**.
- Validate again.

> **Note:** Some corporate networks block SSH; use HTTPS with a personal access token instead:
> ```bash
> uv add git+https://<token>@gitlab.com/synapsis/my-utils.git
> ```

---

## 3. Version Tag Not Resolved on Install

**Symptoms**
```text
uv add git+ssh://git@gitlab.com/synapsis/my-utils.git@v0.1.1
Updating uv.lock... (nothing changes)
```

**Fixes**
- Ensure tag exists locally: `git tag --list`
- Tag with `git tag v0.1.1` then push `git push origin v0.1.1`.
- Confirm remote has the tag: `git ls-remote --tags origin | grep v0.1.1`.
- After pushing, run `uv lock --upgrade-package my-utils` or reinstall.
- If using a commit hash instead of tag, ensure it's pushed too.

---

## 4. PyPI Build or Publish Errors

**Symptoms**
```text
ERROR: Invalid value for '--token': 'pypi-AgE...' has wrong format.
```

**Fixes**
- Ensure token begins with `pypi-`.
- Tokens expire; generate a new one at https://pypi.org/manage/account/#api-tokens.
- Do not hardcode token in repo; store in `.env` and add `.env` to `.gitignore`.
- For build issues, run `uv build --verbose` to see the underlying error.
- Remove any legacy `setup.py` which may conflict with `pyproject.toml`.

---

## 5. `uv build` Produces Empty or Missing Files

**Symptoms**
- `dist/` folder created but contains no `.whl` or `.tar.gz`.
- Build log shows `No matching packages found`.

**Fixes**
- Check that `[tool.hatch.build.targets.wheel]` section in pyproject.toml points to existing packages.
- The package name variables must match folder names (`src/my_utils`).
- If using Poetry or other build-backends previously, remove conflicting configs.

---

## 6. Dependency Resolution Conflicts

**Symptoms**
- Installing library fails due to version conflicts:
  ```text
  ERROR: Cannot install my-utils because these package versions have conflicting dependencies.
  ```

**Fixes**
- Inspect `pyproject.toml` dependencies for overlapping versions that conflict with consumer's requirements.
- Pin ranges carefully (e.g., `requests>=2.28,<3.0`).
- Use `uv lock --strict` to force resolution.

---

## 7. `__init__.py` Exports Incorrect List

**Symptoms**
- `from my_utils import *` brings in private/internal modules or unwanted names.

**Fixes**
- Define `__all__` explicitly with public symbols only.
- Avoid wildcard imports in package modules; use explicit imports in `__init__.py`.

---

Refer to the [Python Library Making Skill](../SKILL.md) for broader context and step-by-step patterns.