[QA] CLI reports “plugin unable to handle environment spec”

[RidaZubair]

Checklist

• I added a descriptive title
• I searched open reports and couldn't find a duplicate
• I can reproduce this issue consistently

What happened?

• If the file has a missing extension PluginError appears
• Unable to create env with rattler-lock-v6 spec

rattler.yml

(test-file) ridaz@MacBook-Pro ~ % conda env create --file=rattler.yml --env-spec=rattler-lock-v6   
2 channel Terms of Service accepted

PluginError: Requested plugin 'rattler-lock-v6' is unable to handle environment spec 'rattler.yml'

(test-file) ridaz@MacBook-Pro ~ % conda export  --format=conda-lock-v1 --file=conda-lock    
(test-file) ridaz@MacBook-Pro ~ % conda env create -n lock2 --file=conda-lock --env-spec=conda-lock-v1 
2 channel Terms of Service accepted

PluginError: Requested plugin 'conda-lock-v1' is unable to handle environment spec 'conda-lock'`

Steps to reproduce

• Create conda-lock file example
  (test-file) ridaz@MacBook-Pro ~ % conda export --format=pixi-lock-v6 --file=pixi.lock
(test-file) ridaz@MacBook-Pro ~ % conda export --format=conda-lock-v1 --file=conda-lock
(test-file) ridaz@MacBook-Pro ~ % conda export --format=rattler-lock-v6 --file=rattler.yml
• Try to export all these files with their respective formats

conda info

(test-file) ridaz@MacBook-Pro ~ % conda info

     active environment : test-file
    active env location : /opt/anaconda3/envs/test-file
            shell level : 2
       user config file : /Users/ridaz/.condarc
 populated config files : /opt/anaconda3/.condarc
                          /Users/ridaz/.condarc
          conda version : 25.9.1
    conda-build version : 25.9.0
         python version : 3.12.8.final.0
                 solver : libmamba (default)
       virtual packages : __archspec=1=m1
                          __conda=25.9.1=0
                          __osx=26.0.1=0
                          __unix=0=0
       base environment : /opt/anaconda3  (writable)
      conda av data dir : /opt/anaconda3/etc/conda
  conda av metadata url : None
           channel URLs : https://repo.anaconda.com/pkgs/main/osx-arm64
                          https://repo.anaconda.com/pkgs/main/noarch
                          https://repo.anaconda.com/pkgs/r/osx-arm64
                          https://repo.anaconda.com/pkgs/r/noarch
          package cache : /opt/anaconda3/pkgs
                          /Users/ridaz/.conda/pkgs
       envs directories : /opt/anaconda3/envs
                          /Users/ridaz/.conda/envs
               platform : osx-arm64
             user-agent : conda/25.9.1 requests/2.32.3 CPython/3.12.8 Darwin/25.0.0 OSX/26.0.1 solver/libmamba conda-libmamba-solver/25.4.0 libmambapy/2.0.5 aau/0.7.3 c/. s/. e/. a/.
                UID:GID : 501:20
             netrc file : None
           offline mode : False

conda list --show-channel-urls

(test-file) ridaz@MacBook-Pro ~ % conda list --show-channel-urls
# packages in environment at /opt/anaconda3/envs/test-file:
#
# Name                     Version          Build               Channel
bzip2                      1.0.8            h80987f9_6          defaults
ca-certificates            2025.11.4        hca03da5_0          defaults
expat                      2.7.3            h982b769_0          defaults
libcxx                     20.1.8           hd7fd590_1          defaults
libffi                     3.4.4            hca03da5_1          defaults
libmpdec                   4.0.0            h80987f9_0          defaults
libzlib                    1.3.1            h5f15de7_0          defaults
lz4-c                      1.9.4            h313beb8_1          defaults
ncurses                    6.5              hee39554_0          defaults
openssl                    3.0.18           h9b4081a_0          defaults
pip                        25.2             pyh0d26453_1        defaults
python                     3.14.0           h1858270_101_cp314  defaults
python_abi                 3.14             1_cp314             defaults
readline                   8.3              h0b18652_0          defaults
sqlite                     3.51.0           hab6afd1_0          defaults
tk                         8.6.15           hcd8a7d5_0          defaults
tzdata                     2025b            h04d1e81_0          defaults
xz                         5.6.4            h80987f9_1          defaults
zlib                       1.3.1            h5f15de7_0          defaults
zstd                       1.5.7            h817c040_0          defaults

Lockfile Information

No response

Additional Context

No response

[travishathaway]

@kenodegard and @RidaZubair,

I'm wondering what we expect to happen here instead. Should we only support filenames with a .lock, .yml or .yaml file extension? Should we also enforce this when creating a lock file?

[travishathaway]

Please see the above pull request for a possible solution to this problem.

[RidaZubair]

@travishathaway
From a user experience perspective, the behavior should be consistent and predictable:

• If we intend to allow creating/exporting lock files without an extension, then those files should work as expected even without .lock, .yml, or .yaml. Users shouldn’t be blocked or confused by missing extensions.
• If files without supported extensions are not intended to be supported, then we should enforce this at the time of creation/export with a clear validation message guiding users to use one of the supported extensions. This ensures users understand what’s expected and avoids ambiguous file handling.

[kenodegard]

The issue is that can_handle currently serves two purposes: auto-detecting format from filename and validating the file is correct. Let's separate them. Keep can_handle for filename-based auto-detection only. Add a separate validate method that checks file contents. When no --env-spec is provided, run auto-detection then validation. When --env-spec is explicitly provided, skip auto-detection and only validate contents. This lets users use any filename they want as long as the contents are valid.

[soapy1]

can_handle currently serves two purposes: auto-detecting format from filename and validating the file is correct

I really think it would be good to move away from auto-detecting format from filename. There is not enough information in a filename in order to autodetect a format. For example, currently conda is does not force any file name restrictions on environment files (other than having a .yaml suffix). An environment.yaml file can be environment.yaml, env.yaml, something.yaml, etc. That means using the auto-detect from filename idea, a new plugin that takes a yaml format will always have collisions with the environment.yaml format during detection.

Instead, can_handle should implement validation on the specification of the file. For example, the environment.yaml spec is defined in cep-24 . So, the can_handle function for the environment.yaml function checks that the provided file satisfies all the requirements and constraints of that spec.

When no --env-spec is provided, run auto-detection then validation. When --env-spec is explicitly provided, skip auto-detection and only validate contents.

This should be handled by the plugin manager..

We could rename can_handle -> validate or something else if that makes things more clear?