Postmortem: SentenceTransformer Missing config_sentence_transformers.json

Summary

The error FileNotFoundError: No such file or directory: ...config_sentence_transformers.json occurs when loading sentence-transformers/all-MiniLM-L6-v2 due to a version mismatch between the installed sentence-transformers library and the model’s requirements. The config_sentence_transformers.json file was introduced in version 2.0 of sentence-transformers, and older library versions cannot parse models that expect this configuration file.

Key takeaway: This is not a cache or download issue—it’s a library version problem.

Root Cause

The root cause is backward incompatibility introduced in sentence-transformers version 2.0:

• Models uploaded to the Hugging Face Hub after version 2.0 include a config_sentence_transformers.json file
• This configuration file contains model-specific settings like max_seq_length, do_normalize_outputs, and pooling_mode
• When using an older version of sentence-transformers (pre-2.0), the library attempts to load this file but fails because it doesn’t recognize the format or expects different configuration keys
• The error manifests as a missing file even when the file exists—the library simply doesn’t know how to handle it

Why This Happens in Real Systems

This issue appears in production systems for several reasons:

• Pinned outdated dependencies: Docker images or requirements.txt files pinning sentence-transformers<2.0
• Inherited codebases: Projects created when sentence-transformers was in early development stages
• Environment inconsistency: Development machines have updated packages while production containers do not
• Mixed library versions: Installing transformers updates without updating sentence-transformers accordingly

Real-World Impact

• Deployment failures: Models work locally but fail in production containers
• Silent model degradation: Some users work around it by loading via transformers directly, losing sentence-transformers optimizations
• Debugging time waste: The misleading “missing file” error leads teams to clear caches repeatedly without addressing the real issue

Example or Code (if necessary and relevant)

The error occurs when running:

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

Check your installed version:

import sentence_transformers
print(sentence_transformers.__version__)

How Senior Engineers Fix It

Senior engineers fix this by addressing the dependency directly:

• Upgrade sentence-transformers: Run pip install -U sentence-transformers to get version 2.2 or later
• Pin correct versions: Update requirements.txt with sentence-transformers>=2.0
• Verify in CI/CD: Add version checks in deployment pipelines to catch outdated dependencies
• Use Docker base images with recent packages: Avoid older Python images that bundle outdated libraries

The fix is a single package upgrade—the model files are not corrupted.

Why Juniors Miss It

Juniors miss this issue because:

• The error message says “missing file” which suggests a download or cache problem
• They follow the error literally and clear caches, re-download models, or try custom cache folders
• They don’t check library version as a first step when seeing configuration errors
• The Hugging Face ecosystem has many interdependencies that mask the real cause
• Documentation often assumes users are on recent library versions and doesn’t explicitly mention the 2.0 breaking change