hankcs/HanLP · error · ConnectionError

Hugging Face 🤗 Transformers failed to download because your

Error message

Hugging Face 🤗 Transformers failed to download because your Internet connection is either off or bad.
See https://hanlp.hankcs.com/docs/install.html#server-without-internet for solutions.

What it means

Hugging Face Transformers surfaces network failures as ValueError containing 'Internet connection'; HanLP intercepts that and re-raises it as a ConnectionError pointing at the offline-install docs. It means the model download from the HF hub could not complete.

Source

Thrown at hanlp/utils/component_util.py:120

                # noinspection PyUnresolvedReferences
                obj.load_transform(save_dir)
            else:
                if os.path.isfile(os.path.join(save_dir, 'config.json')):
                    obj.load(save_dir, verbose=verbose, **kwargs)
                else:
                    obj.load(metapath, **kwargs)
            obj.config['load_path'] = load_path
        return obj
    except ModuleNotFoundError as e:
        if isdebugging():
            raise e from None
        else:
            raise ModuleNotFoundError(
                f'Some modules ({e.name} etc.) required by this model are missing. Please install the full version:'
                '\n\n\tpip install hanlp[full] -U') from None
    except ValueError as e:
        if e.args and isinstance(e.args[0], str) and 'Internet connection' in e.args[0]:
            raise ConnectionError(
                'Hugging Face 🤗 Transformers failed to download because your Internet connection is either off or bad.\n'
                'See https://hanlp.hankcs.com/docs/install.html#server-without-internet for solutions.') \
                from None
        raise e from None
    except Exception as e:
        # Some users often install an incompatible tf and put the blame on HanLP. Teach them the basics.
        try:
            you_installed_wrong_versions, extras = check_version_conflicts(extras=('full',) if tf_model else None)
        except Exception as check_e:
            you_installed_wrong_versions, extras = None, None
        if you_installed_wrong_versions:
            raise version.NotCompatible(you_installed_wrong_versions + '\nPlease reinstall HanLP in the proper way:' +
                                        '\n\n\tpip install --upgrade hanlp' + (
                                            f'[{",".join(extras)}]' if extras else '')) from None
        eprint(f'Failed to load {identifier}')
        from pkg_resources import parse_version
        model_version = meta.get("hanlp_version", '2.0.0-alpha.0')
        if model_version == '2.0.0':  # Quick fix: the first version used a wrong string

View on GitHub (pinned to ddb1299bdd)

Solutions

1. Follow the linked doc (https://hanlp.hankcs.com/docs/install.html#server-without-internet): pre-download models on an internet machine and copy the cache to the offline server.
2. Fix proxy/network: export HTTP(S)_PROXY, or whitelist huggingface.co endpoints.
3. Clear any corrupt partial download in the HF/HanLP cache and retry once network is up.

import socket
try:
    socket.create_connection(('huggingface.co', 443), timeout=5)
except OSError:
    raise RuntimeError('offline: pre-download model cache first')

try:
    m = hanlp.load(mid)
except ConnectionError:
    m = hanlp.load(local_path)  # pre-downloaded copy

When it happens

Trigger: hanlp.load() of a transformer model on a machine with no/blocked internet, behind a proxy that breaks the download, or with a full/partial download cache that retries and fails.

Common situations: Air-gapped servers; corporate proxies/firewalls blocking huggingface.co; flaky connections during first model download; DNS failures inside containers.

Related errors

• transformers has its own tagger, not need to convert idx for
• transformers has its own tagger, not need to convert idx for
• The class `PretrainedBartModel` has been depreciated, please
• `do_basic_tokenize=False` might not work when `use_fast=True

AI-assisted analysis of hankcs/HanLP@ddb1299bdd (2026-08-27). Data as JSON: /api/errors/f90d8137db396ddf. Report an issue: GitHub.