[Bug] AttributeError: module 'idna' has no attribute 'IDNAError' when I run qmk

[adiabatic]

Describe the Bug

I wanted to update my keyboard layout by adding another Caps Lock key (long story), so I ran qmk userspace-compile. However, I got the following error:

~/Projects/zweihander (main) > qmk userspace-compile
Traceback (most recent call last):
  File "/opt/homebrew/bin/qmk", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/opt/homebrew/Cellar/qmk/1.1.5_1/libexec/lib/python3.12/site-packages/qmk_cli/script_qmk.py", line 76, in main
    import qmk.cli  # noqa
    ^^^^^^^^^^^^^^
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/cli/__init__.py", line 253, in <module>
    __import__(subcommand)
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/cli/ci/validate_aliases.py", line 5, in <module>
    from qmk.keyboard import resolve_keyboard, keyboard_folder, keyboard_alias_definitions
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/keyboard.py", line 10, in <module>
    import qmk.path
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/path.py", line 8, in <module>
    from qmk.constants import MAX_KEYBOARD_SUBFOLDERS, QMK_FIRMWARE, QMK_USERSPACE, HAS_QMK_USERSPACE
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/constants.py", line 7, in <module>
    from qmk.userspace import detect_qmk_userspace
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/userspace.py", line 6, in <module>
    import jsonschema
  File "/opt/homebrew/Cellar/qmk/1.1.5_1/libexec/lib/python3.12/site-packages/jsonschema/__init__.py", line 13, in <module>
    from jsonschema._format import FormatChecker
  File "/opt/homebrew/Cellar/qmk/1.1.5_1/libexec/lib/python3.12/site-packages/jsonschema/_format.py", line 287, in <module>
    raises=(idna.IDNAError, UnicodeError),
            ^^^^^^^^^^^^^^
AttributeError: module 'idna' has no attribute 'IDNAError'

I get this error whenever I run qmk, no matter what I put after it, whether it's nothing, userspace-compile, or --help.

Keyboard Used

ergodox_ez

Link to product page (if applicable)

No response

Operating System

macOS 14.5 (Sonoma)

qmk doctor Output

Traceback (most recent call last):
  File "/opt/homebrew/bin/qmk", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/opt/homebrew/Cellar/qmk/1.1.5_1/libexec/lib/python3.12/site-packages/qmk_cli/script_qmk.py", line 76, in main
    import qmk.cli  # noqa
    ^^^^^^^^^^^^^^
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/cli/__init__.py", line 253, in <module>
    __import__(subcommand)
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/cli/ci/validate_aliases.py", line 5, in <module>
    from qmk.keyboard import resolve_keyboard, keyboard_folder, keyboard_alias_definitions
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/keyboard.py", line 10, in <module>
    import qmk.path
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/path.py", line 8, in <module>
    from qmk.constants import MAX_KEYBOARD_SUBFOLDERS, QMK_FIRMWARE, QMK_USERSPACE, HAS_QMK_USERSPACE
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/constants.py", line 7, in <module>
    from qmk.userspace import detect_qmk_userspace
  File "/Users/comatoast/Projects/Others/qmk_firmware/lib/python/qmk/userspace.py", line 6, in <module>
    import jsonschema
  File "/opt/homebrew/Cellar/qmk/1.1.5_1/libexec/lib/python3.12/site-packages/jsonschema/__init__.py", line 13, in <module>
    from jsonschema._format import FormatChecker
  File "/opt/homebrew/Cellar/qmk/1.1.5_1/libexec/lib/python3.12/site-packages/jsonschema/_format.py", line 287, in <module>
    raises=(idna.IDNAError, UnicodeError),
            ^^^^^^^^^^^^^^
AttributeError: module 'idna' has no attribute 'IDNAError'

Is AutoHotKey / Karabiner installed

• AutoHotKey (Windows)
• Karabiner (macOS)

Other keyboard-related software installed

No response

Additional Context

No response

[adiabatic]

I tried the advice in a now-deleted comment, but I didn't actually do anything with it and just uninstalled it after clicking through the email back to this page. I didn't try running qmk again.

Warning: python-idna has been deprecated because it does not meet homebrew/core's requirements for Python library formulae!
…
==> Caveats
Additional details on upcoming formula removal are available at:
* https://github.com/Homebrew/homebrew-core/issues/157500
* https://docs.brew.sh/Python-for-Formula-Authors#libraries
* https://docs.brew.sh/Homebrew-and-Python#pep-668-python312-and-virtual-environments

[fauxpark]

I'm not actually sure what the problem here is, but I know for a fact that installing python-idna will not help - for starters, I can run the CLI just fine without it on my machine. Secondly, installing a Python formula globally is not a valid solution because the CLI formula is run in a venv. Its Python dependencies are pinned to specific versions and do not include anything related to IDNA.

The only thing I can really suggest is that there is something wrong with your environment and nuking your Brew install entirely may fix it.

[sbmueller]

I know for a fact that installing python-idna will not help

It resolved the issue for me. Afterward, the compiler tool chain could not be found, so I needed to qmk setup again. Now everything works again.
I didn't use qmk for some time and only can speculate some brew upgrade did break something.

[adiabatic]

I didn't use qmk for some time and only can speculate some brew upgrade did break something.

Well, this is the boat I'm in.

[fauxpark]

It resolved the issue for me.

Sure, but it is not the correct solution, because the package the error is coming from (jsonschema) does not actually require idna to run:
https://github.com/python-jsonschema/jsonschema/blob/main/jsonschema/_format.py#L284-L298

As you can see here this entire block is wrapped in a with suppress(ImportError) so it should get completely skipped over if the idna package is not installed. Even if it is, the specific thing the trace is pointing out, IDNAError, does in fact exist, and has existed, if you look at that package's code.

Because the CLI is confirmed working without need for this IDNA package, and I can't reproduce this error on my own, I can only guess that there is simply something wrong with your Brew install, or your environment at large. As far as I can tell this is not a problem with the QMK CLI or formula.

Please make sure your qmk_firmware repo is up to date, your Brew install is up to date and clean (run brew doctor), you have only [email protected] installed, and none of the QMK CLI's Python dependencies are installed globally through pip (because this is all handled by the formula in a venv as I mentioned). For example I only have certifi, pip and wheel installed.

[sigprof]

Looks like Python is finding some idna.py or idna/__init__.py file in its module search path, but it's not an expected version of the idna package. You may try running something like python -c 'import idna; print(idna)' to find out where that package is actually located, except you need to run the specific version of Python used by qmk, not just python.

[sbmueller]

This seems also to work:

• brew uninstall python-idna
• pip3 install --break-system-packages idna
• pip3 uninstall --break-system-packages idna

Weirdly idna was present in my python site-packages but not listed as installed by pip nor brew, so no idea where it came from. Installing + uninstalling with pip resolved it for me.

[adiabatic]

I can confirm that

brew uninstall python-idna
pip3 install --break-system-packages idna
pip3 uninstall --break-system-packages idna

also worked for me. Go figure.

Thanks everyone for the help debugging!