Skip to content

Troubleshooting

Note: Can you help improve this file? Edit this file and submit a pull request with your improvements!

just: command not found

just is the task runner used by the generated project. It needs to be installed separately from uv. On macOS: brew install just. See the just installation docs for other platforms.

Docs site shows 404

Make sure GitHub Pages is configured to deploy from GitHub Actions (not a branch). Go to your repo's Settings > Pages and set the source to GitHub Actions. Then enable the generated deployment workflow:

gh variable set DOCS_DEPLOYMENT_ENABLED --repo OWNER/REPOSITORY --body true

Push to main or go to Actions, find the "Documentation" workflow, and run it manually.

Release didn't publish to PyPI

The most common causes:

  • Trusted Publisher not configured. You need to register your repo as a trusted publisher on PyPI before the first release. See the PyPI Release Checklist.
  • pypi environment not created. The post-generation hook attempts this only when you opt into GitHub setup. Go to Settings > Environments and create an environment named pypi.
  • Tag format wrong. Tags must match v* (e.g., v0.1.0). The just release command handles this for you.

If just release reports that a tag or GitHub Release already exists, inspect the existing tag and release before retrying. The release script can resume a failed tag push or GitHub Release creation when the tag still points to the current HEAD.

If you got the Trusted Publisher configuration wrong, you can delete it on PyPI and create it again.

Type checker reports errors

ty runs with all rules enabled as errors by default. If you see errors from third-party library types, you can relax specific rules in pyproject.toml:

[tool.ty]
rules.TY015 = "warn"  # Change from error to warning

See the ty documentation for the full list of rules.

Windows issues

  • Some people have reported issues using git bash. Try using the Command Terminal instead.
  • If you run into environment issues, make sure uv is installed and run uv sync from your project directory. uv handles virtual environments automatically.