{"record":{"id":"f90d8137db396ddf","repo":"hankcs/HanLP","slug":"hugging-face-transformers-failed-to-download-be","errorCode":null,"errorMessage":"Hugging Face 🤗 Transformers failed to download because your Internet connection is either off or bad.\nSee https://hanlp.hankcs.com/docs/install.html#server-without-internet for solutions.","messagePattern":"Hugging Face 🤗 Transformers failed to download because your Internet connection is either off or bad\\.\nSee https://hanlp\\.hankcs\\.com/docs/install\\.html#server-without-internet for solutions\\.","errorType":"exception","errorClass":"ConnectionError","httpStatus":null,"severity":"error","filePath":"hanlp/utils/component_util.py","lineNumber":120,"sourceCode":"                # noinspection PyUnresolvedReferences\n                obj.load_transform(save_dir)\n            else:\n                if os.path.isfile(os.path.join(save_dir, 'config.json')):\n                    obj.load(save_dir, verbose=verbose, **kwargs)\n                else:\n                    obj.load(metapath, **kwargs)\n            obj.config['load_path'] = load_path\n        return obj\n    except ModuleNotFoundError as e:\n        if isdebugging():\n            raise e from None\n        else:\n            raise ModuleNotFoundError(\n                f'Some modules ({e.name} etc.) required by this model are missing. Please install the full version:'\n                '\\n\\n\\tpip install hanlp[full] -U') from None\n    except ValueError as e:\n        if e.args and isinstance(e.args[0], str) and 'Internet connection' in e.args[0]:\n            raise ConnectionError(\n                'Hugging Face 🤗 Transformers failed to download because your Internet connection is either off or bad.\\n'\n                'See https://hanlp.hankcs.com/docs/install.html#server-without-internet for solutions.') \\\n                from None\n        raise e from None\n    except Exception as e:\n        # Some users often install an incompatible tf and put the blame on HanLP. Teach them the basics.\n        try:\n            you_installed_wrong_versions, extras = check_version_conflicts(extras=('full',) if tf_model else None)\n        except Exception as check_e:\n            you_installed_wrong_versions, extras = None, None\n        if you_installed_wrong_versions:\n            raise version.NotCompatible(you_installed_wrong_versions + '\\nPlease reinstall HanLP in the proper way:' +\n                                        '\\n\\n\\tpip install --upgrade hanlp' + (\n                                            f'[{\",\".join(extras)}]' if extras else '')) from None\n        eprint(f'Failed to load {identifier}')\n        from pkg_resources import parse_version\n        model_version = meta.get(\"hanlp_version\", '2.0.0-alpha.0')\n        if model_version == '2.0.0':  # Quick fix: the first version used a wrong string","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/hankcs/HanLP/blob/ddb1299bddff079e447af52ec12549c50636bfa8/hanlp/utils/component_util.py#L102-L138","documentation":"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.","triggerScenarios":"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.","commonSituations":"Air-gapped servers; corporate proxies/firewalls blocking huggingface.co; flaky connections during first model download; DNS failures inside containers.","solutions":["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.","Fix proxy/network: export HTTP(S)_PROXY, or whitelist huggingface.co endpoints.","Clear any corrupt partial download in the HF/HanLP cache and retry once network is up."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"import socket\ntry:\n    socket.create_connection(('huggingface.co', 443), timeout=5)\nexcept OSError:\n    raise RuntimeError('offline: pre-download model cache first')","typeGuard":null,"tryCatchPattern":"try:\n    m = hanlp.load(mid)\nexcept ConnectionError:\n    m = hanlp.load(local_path)  # pre-downloaded copy","preventionTips":["Bake pre-downloaded models into Docker images for offline servers.","Configure proxy env vars and verify with a curl to huggingface.co before running."],"tags":["network","offline","transformers","model-download"],"backgroundTag":"model-download-offline","analyzedSha":"ddb1299bddff079e447af52ec12549c50636bfa8","analyzedAt":"2026-08-27T03:36:54.287Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}