# Common Gotchas

If you are encountering problems with a codebase rendered from this template, perhaps one of the
following is happening:

## Poetry

### **`No module named 'jinja2'` when running Poetry commands**

If you installed Poetry via `pipx` and get a `No module named 'jinja2'` error when running any `poetry` command in this project, the cause is the `poetry-dynamic-versioning` plugin.  Poetry installs it into a project-local cache (`.poetry/plugins/`) but does not pull in `jinja2` as a transitive dependency, even though `dunamai` (which `poetry-dynamic-versioning` depends on) needs it at import time.

The fix is to inject `jinja2` into Poetry's `pipx` environment and then clear the stale cache:

``` console
$ pipx inject poetry jinja2
$ rm -rf .poetry/
$ poetry check
```

## Configuring PyPI and TestPyPI

### **'Entire account'-scoped secrets**

'Entire account'-scoped tokens for *PyPI* (and *TestPyPI*) are not ideal, but there is a cold start problem when adding new projects to your account: you need a token to add a new project, but you need a project to create a project-scoped token.  For this reason, you need to create and configure GitHub with a temporary 'Entire account'-scoped token first, and then when you have added the project to *PyPI* and *TestPyPi*, you need to delete the temporary token and repeat the process: create a token scoped to the project and reconfigure *GitHub* with the new secret.  **It's easy to forget to do this.**

## Workflow Issues

### **My checks keep failing**

Have you given workflows write permissions?  If not, navigate within the repo to `Settings->Actions->General` and select `Read and write permissions`.

## Developing Documentation

### **I've added a new markdown file to the `docs/content` directory, but it isn't showing-up in the final rendered documentation**

Have you added it to the `docs/index.rst` file?  Follow the examples there for adding your new content
to the documentation.