`hatch -e <env> run` stopped working with v1.16.0: "Environment ... is not a builder environment"

[janluke]

I can list all environments as usual with hatch env show. But any run command like:

hatch -e <env> run true
hatch -e <env> run <script>

for <env> != default fails with error:

Environment `<env>` is not a builder environment

This started with v1.16.0.

[cjames23]

Can you provide a more reproducible example? Were these existing environments? If you did hatch env prune and re-ran do you still get the error?

hatch -e types run check
Success: no issues found in 18 source files

I am not able to reproduce this on v1.16.0

[janluke]

I'll try to reproduce on a minimal example later (the actual file has private dependencies and it's quite large). I'm quite busy at work right now.

I can say it happened in a GitHub Actions workflow first, then I reproduced it locally. Pinning to 1.15.1 resolved the issue both locally and in GH Actions.

This is the command I run in the workload:

hatch -e tasks run <irrelevant command>

This is the environment configuration:

[envs.tasks]
detached = true
python = "3.11"
features = ["tasks"]

This is part of pyproject.toml:

[build-system]
requires = ["hatchling", "hatch-vcs", "hatch-requirements-txt"]
build-backend = "hatchling.build"

[project]
# ...
dynamic = ["version", "dependencies", "optional-dependencies"]
requires-python = ">=3.11"

[tool.hatch.metadata.hooks.requirements_txt]
files = [
  "requirements/app.txt",
  "requirements/cli.txt",
  "requirements/test.txt",
  "requirements/lint.txt",
  "requirements/tasks.txt",
]

[tool.hatch.metadata.hooks.requirements_txt.optional-dependencies]
app = ["requirements/app.txt"]
cli = ["requirements/cli.txt"]
test = ["requirements/test.txt"]
lint = ["requirements/lint.txt"]
tasks = ["requirements/tasks.txt"]

Might be related to hatch-requirements-txt plugin?

[cjames23]

It might be that the changes for 1.16.0 have impacted the hatch-requirements-txt plugin with changes to allow dependency groups and workspaces with editable installs.

[chdemko]

I have the same kind of issue using only hatch-vcs:

[tool.hatch.envs.hatch-test]
extra-dependencies = [
  "myproject.docs @ file://extra.docs/"
]

in the extra.docs folder, I have a hatch_build.py file:

    def update(self, metadata: dict[str, object]) -> None:
        source_path = Path(self.root, "..", "pyproject.toml")
        if source_path.exists():
            with source_path.open("rb") as f:
                source_metadata = tomllib.load(f)
                project = source_metadata["project"]
            result = subprocess.run(
                ["hatch", "version"],
                capture_output=True,
                text=True,
                cwd=Path(self.root, ".."),
                check=True,
            )
            version = result.stdout.strip()
            # Set version and name
            metadata["version"] = version
            ...

and a pyproject.toml file containing:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "docs"
dynamic = [
  "version",
  "description",
  "requires-python",
  "license",
  "authors",
  "maintainers",
  "keywords",
  "classifiers",
  "dependencies"
]

[tool.hatch.build.hooks.custom]

[tool.hatch.metadata.hooks.custom]

At final, I have this error:

CompletedProcess(args='hatch version', returncode=1, stdout='', stderr='Environment `hatch-test.py3.12` is not a builder environment\n')

This error was not present with hatch 1.15

[chdemko]

I have a tiny sample:

$ unzip sample.zip
$ cd sample
$ hatch build
dist/sample-0.0.0.tar.gz
dist/sample-0.0.0-py2.py3-none-any.whl
$ hatch run docs:build
Sphinx v8.2.3 en cours d'exécution
Environment `docs` is not a builder environment

Configuration error!
...

If I empty the docs/conf.py file or if I use hatch 1.15, or if I add builder = true in the pyproject.toml file:

[tool.hatch.envs.docs]
dependencies = [
  "Sphinx~=8.2",
]
builder = true

I have no errors.

sample.zip

[cjames23]

This is the change that causes the issue

    @cached_property
    def build_env(self) -> EnvironmentInterface:
        # Prevent the default environment from being used as a builder environment
        environment = self.get_environment("hatch-build" if self.app.env == "default" else self.app.env)
        if not environment.builder:
            self.app.abort(f"Environment `{environment.name}` is not a builder environment")

        return environment

And this was a part of the changes noted in the change log as

Environment type plugins are now no longer expected to support a pseudo-build environment as any environment now may be used for building. The following methods have been removed: build_environment, build_environment_exists, run_builder, construct_build_command

The correct fix for users is to mark an environment being used as a builder with builder = true. We will investigate if we can provide backwards compatibility for this.

[chdemko]

Perhaps this could be specified in the documentation?

[ovidiu-eremia]

I have the same issue. Previous version of hatch worked when running scripts from an environment plugin (hatch-pip-compile) but now it raises: Environment <my env name> is not a builder environment.

I've added the builder=true option to the environment and I don't get the error anymore but now it requires hatchling as a dependency, so I needed to add that also to the environment dependencies...

Any advice is welcome. Thank you!

[cjames23]

Perhaps this could be specified in the documentation?

Yes we will work on getting this into the documentation. I am still trying to figure out how to get backwards compatibility for this change. Admittedly this is a piece of code I am less familiar with than Ofek.