Cannot Find an Appropriate Cached Snapshot Folder Error? A Complete Guide to Solving Hugging Face Download Issues

As an AI developer, when you eagerly write from_pretrained, the last thing you want to see is a bright red error message. Many Hugging Face users have likely encountered this error:

err[msg]=Cannot find an appropriate cached snapshot folder for the specified revision on the local disk and outgoing traffic has been disabled. To enable repo look-ups and downloads online, pass 'local_files_only=False' as input.

Don't worry—this usually isn't a major issue. However, it can be the start of a "chain of problems," especially for developers in mainland China. This article will help you understand and resolve this error from the root, offering best practices tailored to network environments in China, so you and your team can say goodbye to model download frustrations.

Step 1: Understanding and Fixing the local_files_only Error

The error message is quite straightforward and can be broken down into two parts:

1. "Cannot find an appropriate cached snapshot folder... on the local disk": The program couldn't find the required model files in your local cache directory.
2. "and outgoing traffic has been disabled": The code's setting (local_files_only=True) prevents it from connecting to Hugging Face Hub to download the files.

In simple terms, it means: "I don't have what I need locally, and you won't let me go online to get it, so I have to throw an error."

How to Fix It?

The error message itself provides the solution: Allow the program to download from the internet.

You just need to explicitly set the parameter local_files_only=False in the function that loads the model or tokenizer.

Example of Incorrect Code:

from transformers import AutoModel

# This setting blocks network downloads and will cause an error if the local cache is missing
model = AutoModel.from_pretrained("google-bert/bert-base-cased", local_files_only=True)

Corrected Code:

from transformers import AutoModel

# Set to False to allow automatic online downloads when the local cache is not found
model = AutoModel.from_pretrained("google-bert/bert-base-cased", local_files_only=False)

Note: In many recent versions of the transformers library, the default value for local_files_only is already False. If you encounter this error, it means your code or environment explicitly set it to True.

After resolving this, you might breathe a sigh of relief and run the code again. But soon, a new issue may arise—the program gets stuck on Downloading... and eventually ends with a Connection Timeout.

Step 2: Solving Network Issues in China—Timeouts and Connection Failures

This happens because Hugging Face servers are located overseas and, due to well-known reasons, are not directly accessible from mainland China.

Fortunately, there are mature and simple solutions. Using a domestic mirror is highly recommended.

Best Solution: Use a Domestic Mirror (hf-mirror.com)

The community-driven mirror hf-mirror.com is currently the most recommended, stable, and reliable Hugging Face mirror. You don't need to modify any Python code; just set one environment variable.

The huggingface_hub library automatically recognizes the HF_ENDPOINT environment variable and redirects all download requests to this domestic mirror, enabling fast and stable downloads.

How to Set It Up:

Before running your Python program, execute the following command in your terminal:

• Linux / macOS Users:

  export HF_ENDPOINT=https://hf-mirror.com

• Windows (CMD) Users:

  set HF_ENDPOINT=https://hf-mirror.com

• Windows (PowerShell) Users:

  $env:HF_ENDPOINT = "https://hf-mirror.com"

• Setting in Python Code

  import os
  os.environ['HF_ENDPOINT']='https://hf-mirror.com'

Once set, you can run your Python script as usual, and the download speed will improve dramatically.

Alternative Solution: Set Up a Network Proxy

If you already have a stable and reliable proxy tool, you can also solve the issue by setting proxy environment variables. Assuming your proxy is on localhost 127.0.0.1 and port 7890:

• Linux / macOS:

  export HTTP_PROXY=http://127.0.0.1:7890
  export HTTPS_PROXY=http://127.0.0.1:7890

• Windows (CMD):

  set HTTP_PROXY=http://127.0.0.1:7890
  set HTTPS_PROXY=http://127.0.0.1:7890

Although this method works, using the mirror (HF_ENDPOINT) is more recommended, stable, and focused for solving Hugging Face download issues specifically.

All-in-One Solution

Next time you encounter the Cannot find an appropriate cached snapshot folder error or any Hugging Face download-related network issues, follow these two steps for a permanent fix:

1. Check Your Code: Ensure you haven't mistakenly set local_files_only=True in the from_pretrained function. If internet access is needed, remove this parameter or set it to local_files_only=False.

2. Configure Your Environment (Essential for Users in China): Set the HF_ENDPOINT environment variable in your terminal or system.

   export HF_ENDPOINT=https://hf-mirror.com