#6960·beets

Imporve error message when MusicBrainz is unreachable

Author: emihamCreated Aug 29, 2026Updated Sep 9, 2026
Labelsmusicbrainz

Problem

Running beet import ... when MusicBrainz is down (as it's been quite a bit lately) throws an exception that should probably be caught and printed as a more readable error message:

musicbrainz: Error searching MusicBrainz: HTTPSConnectionPool(host='musicbrainz.org', port=443): Max retries exceeded with url: /ws/2/release?limit=10&query=release%3A%28haniwa%29+artist%3A%28kiyohiko+senba+and+his+haniwa+all+stars%29+date%3A%281983%29+catno%3A%28srcl2133%29&fmt=json (Caused by SSLError(SSLEOFError(8, '[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1082)')))
Traceback (most recent call last):
  File "/usr/lib/python3.14/site-packages/urllib3/connectionpool.py", line 464, in _make_request
    self._validate_conn(conn)
    ~~~~~~~~~~~~~~~~~~~^^^^^^
  File "/usr/lib/python3.14/site-packages/urllib3/connectionpool.py", line 1106, in _validate_conn
    conn.connect()
    ~~~~~~~~~~~~^^
  File "/usr/lib/python3.14/site-packages/urllib3/connection.py", line 796, in connect
    sock_and_verified = _ssl_wrap_socket_and_match_hostname(
        sock=sock,
    ...<14 lines>...
        assert_fingerprint=self.assert_fingerprint,
    )
  File "/usr/lib/python3.14/site-packages/urllib3/connection.py", line 975, in _ssl_wrap_socket_and_match_hostname
    ssl_sock = ssl_wrap_socket(
        sock=sock,
    ...<8 lines>...
        tls_in_tls=tls_in_tls,
    )
  File "/usr/lib/python3.14/site-packages/urllib3/util/ssl_.py", line 433, in ssl_wrap_socket
    ssl_sock = _ssl_wrap_socket_impl(sock, context, tls_in_tls, server_hostname)
  File "/usr/lib/python3.14/site-packages/urllib3/util/ssl_.py", line 477, in _ssl_wrap_socket_impl
    return ssl_context.wrap_socket(sock, server_hostname=server_hostname)
           ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/ssl.py", line 455, in wrap_socket
    return self.sslsocket_class._create(
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        sock=sock,
        ^^^^^^^^^^
    ...<5 lines>...
        session=session
        ^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/lib/python3.14/ssl.py", line 1076, in _create
    self.do_handshake()
    ~~~~~~~~~~~~~~~~~^^
  File "/usr/lib/python3.14/ssl.py", line 1372, in do_handshake
    self._sslobj.do_handshake()
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^
ssl.SSLEOFError: [SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1082)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/lib/python3.14/site-packages/urllib3/connectionpool.py", line 788, in urlopen
    response = self._make_request(
        conn,
    ...<10 lines>...
        **response_kw,
    )
  File "/usr/lib/python3.14/site-packages/urllib3/connectionpool.py", line 488, in _make_request
    raise new_e
urllib3.exceptions.SSLError: [SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1082)

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/lib/python3.14/site-packages/requests/adapters.py", line 696, in send
    resp = conn.urlopen(
        method=request.method,
    ...<9 lines>...
        chunked=chunked,
    )
  File "/usr/lib/python3.14/site-packages/urllib3/connectionpool.py", line 872, in urlopen
    return self.urlopen(
           ~~~~~~~~~~~~^
        method,
        ^^^^^^^
    ...<13 lines>...
        **response_kw,
        ^^^^^^^^^^^^^^
    )
    ^
  File "/usr/lib/python3.14/site-packages/urllib3/connectionpool.py", line 872, in urlopen
    return self.urlopen(
           ~~~~~~~~~~~~^
        method,
        ^^^^^^^
    ...<13 lines>...
        **response_kw,
        ^^^^^^^^^^^^^^
    )
    ^
  File "/usr/lib/python3.14/site-packages/urllib3/connectionpool.py", line 872, in urlopen
    return self.urlopen(
           ~~~~~~~~~~~~^
        method,
        ^^^^^^^
    ...<13 lines>...
        **response_kw,
        ^^^^^^^^^^^^^^
    )
    ^
  [Previous line repeated 3 more times]
  File "/usr/lib/python3.14/site-packages/urllib3/connectionpool.py", line 842, in urlopen
    retries = retries.increment(
        method, url, error=new_e, _pool=self, _stacktrace=sys.exc_info()[2]
    )
  File "/usr/lib/python3.14/site-packages/urllib3/util/retry.py", line 543, in increment
    raise MaxRetryError(_pool, url, reason) from reason  # type: ignore[arg-type]
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
urllib3.exceptions.MaxRetryError: HTTPSConnectionPool(host='musicbrainz.org', port=443): Max retries exceeded with url: /ws/2/release?limit=10&query=release%3A%28haniwa%29+artist%3A%28kiyohiko+senba+and+his+haniwa+all+stars%29+date%3A%281983%29+catno%3A%28srcl2133%29&fmt=json (Caused by SSLError(SSLEOFError(8, '[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1082)')))

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/lib/python3.14/site-packages/beets/metadata_plugins.py", line 420, in _search_api
    response_data = self.get_search_response(params)
  File "/usr/lib/python3.14/site-packages/beetsplug/musicbrainz.py", line 761, in get_search_response
    return self.mb_api.search(
           ~~~~~~~~~~~~~~~~~~^
        mb_entity, dict(params.filters), limit=params.limit
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/usr/lib/python3.14/site-packages/beetsplug/_utils/musicbrainz.py", line 685, in search
    return self._get_resource(entity, **kwargs)[f"{normalised_entity}s"]
           ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/beetsplug/_utils/musicbrainz.py", line 637, in _get_resource
    return self.get_json(f"{self.api_root}/{resource}", params=kwargs)
           ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/beetsplug/_utils/musicbrainz.py", line 623, in get_json
    return self._normalize_data(super().get_json(*args, **kwargs))
                                ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/beetsplug/_utils/requests.py", line 227, in get_json
    return self.get(*args, **kwargs).json()
           ~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/beetsplug/_utils/requests.py", line 215, in get
    return self.request("get", *args, **kwargs)
           ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/beetsplug/_utils/musicbrainz.py", line 619, in request
    return super().request(*args, **kwargs)
           ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/beetsplug/_utils/requests.py", line 211, in request
    return self.session.request(*args, **kwargs)
           ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/beetsplug/_utils/requests.py", line 100, in request
    r = super().request(*args, **kwargs)
  File "/usr/lib/python3.14/site-packages/requests/sessions.py", line 651, in request
    resp = self.send(prep, **send_kwargs)
  File "/usr/lib/python3.14/site-packages/requests_ratelimiter/requests_ratelimiter.py", line 104, in send
    response = super().send(request, **kwargs)
  File "/usr/lib/python3.14/site-packages/requests/sessions.py", line 784, in send
    r = adapter.send(request, **kwargs)
  File "/usr/lib/python3.14/site-packages/beetsplug/_utils/requests.py", line 135, in send
    return super().send(request, *args, **kwargs)
           ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/lib/python3.14/site-packages/requests/adapters.py", line 727, in send
    raise SSLError(e, request=request)
requests.exceptions.SSLError: HTTPSConnectionPool(host='musicbrainz.org', port=443): Max retries exceeded with url: /ws/2/release?limit=10&query=release%3A%28haniwa%29+artist%3A%28kiyohiko+senba+and+his+haniwa+all+stars%29+date%3A%281983%29+catno%3A%28srcl2133%29&fmt=json (Caused by SSLError(SSLEOFError(8, '[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1082)')))

Setup

  • Python version: 3.14.7
  • beets version: 2.13.1