Common Pitfalls in Sharing Open Source Models on Hugging Face (and How to Dodge Them)

Hugging Face has become the de facto platform for sharing open-source AI models. But you need to be careful when uploading your models if you want your model to be truly usable and discoverable.

In this post, we share key insights we’ve gained through hands-on work with customers uploading Transformer models to Hugging Face. From fine-tuned LLMs to quantized adapters and custom pipelines, we’ve seen the common pitfalls developers run into—and how to fix them. These tips come from real-world experience and will help you make your models not just functional, but easy to find and use.

Uploading your model with the right metadata and documentation isn’t just a nice-to-have—it directly influences how easily models can be found. Even a great model can be overlooked if it lacks proper tags, templates, or a clear model card. In contrast, a well-documented model is more likely to be featured, appear in search and filters, and even trend on the Hugging Face Hub.

What Are Model Cards?

A model card is a README.md file, written in Markdown format, that includes both human-readable documentation and a YAML front matter block at the top for machine-readable metadata. A good model card improves your model’s discoverability and usability on the Hugging Face Hub.

What Makes a Good Model Card?

A good model card is more than just documentation—it’s a transparent, structured explanation of a machine learning model’s development, intended use, limitations, and performance. It should be clear, honest, and actionable. Here are the key qualities of an effective model card, along with suggestions on how to achieve them:

1. Intended Use & Limitations 🎯

What to include:

• Primary use cases for the model.
• Who the intended users are (e.g., developers, researchers, end-users).
• Known limitations or failure cases.
• Recommended and discouraged uses.

Best Practices:

• Use a table or bulleted list to distinguish “Appropriate Uses” vs. “Out-of-Scope Uses.”
• Add real-world examples and potential misuse cases.
• Be honest about limitations—this increases trust and encourages responsible usage.

2. Training Details 📊

What to include:

• Model architecture (e.g., BERT, GPT, ViT).
• Training dataset summary: sources, size, language coverage, licenses.
• Preprocessing steps and augmentation techniques.
• Training hyperparameters and compute resources.

Best Practices:

• Provide a summary table of dataset characteristics.
• Include links to dataset cards or citations.
• Mention known dataset biases, if applicable.

3. Evaluation Metrics & Results 📈

What to Include:

• Core metrics (accuracy, precision, recall, F1, AUC, etc.)
• Performance on standard benchmarks or held-out validation sets.
• Results broken down by subgroups (age, gender, language, etc.), if applicable.

Best Practices:

• Present metrics in a table format with comparisons to baselines or prior models.
• Include visualizations (e.g., bar charts, confusion matrices) where useful.
• Highlight both strengths and areas needing improvement.

💡 Tip: FriendliAI supports over 400,000 models on Hugging Face and provides optimized inference APIs and scalable deployment—so you can easily test, serve, and monitor your model with minimal setup.

4. Example Usage 💻

What to Include:

• Code snippets showing how to load and use the model.
• Supported input/output formats.
• API endpoints (if deployed as a service).

Best Practices:

• Provide a simple inference example with input prompt and generated output.
• Show edge cases if useful (e.g., multilingual input, long sequences).

5. Citations or References 📚

What to Include:

• Relevant research papers or documentation.
• Datasets used (with links or DOIs).
• Acknowledgments to contributors or funding sources.

Best Practices:

• Use a proper citation format (IEEE, BibTeX, APA, etc.).
• Include links cited resources.

6. Visuals 🎥

What to Include:

• Diagrams of model architecture or pipeline.
• Training curves or loss plots.
• Confusion matrices or attention maps.

Best Practices:

• Keep visuals relevant and not overly complex.
• Include alt-text or captions to describe what each visual shows.
• Use visuals to highlight important findings or behaviors.

7. YAML Front Matter (Metadata) 🤖

YAML Front Matter is metadata located on top of README.md file that contains important tags. These tags significantly boost visibility by enabling auto‑detection and filtering on the Hugging Face Hub.

What to Include:

• Metadata tags used for auto-discovery and categorization.

Best Practices:

• Follow Hugging Face's official model card guide for supported tags.
• Be sure to include tags like pipeline_tag, library_name, and license.

Here’s an example of a minimal YAML Front Matter:

yaml
Copy
---
library_name: transformers
pipeline_tag: image-text-to-text
language:
  - en
base_model:
  - org-name/model-name
tags:
  - pytorch
license: other
license_name: license-name
---

💡 Tip: Hugging Face provides templates for model cards to help you get started.

This metadata is critical for discoverability, filtering, and model reproducibility—and we will cover more about it throughout the rest of this article.

Common Pitfalls

Here are common issues developers run into when uploading models—and how to fix them:

1. Missing chat_template.jinja File or chat_template Field

Why it matters: Hugging Face’s chat interface relies on a chat template to format inputs. Without it, your chat model may not work as expected.

Fix:

• Include a chat_template.jinja file in your repo.
• For legacy support, add chat_template field to tokenizer_config.json.

2. Missing or Incorrect eos_token

Why it matters: The eos_token controls when generation stops. If undefined, models can encounter runtime failures, producing infinite output or failing silently.

Fix: Define eos_token in config.json (and optionally in tokenizer_config.json and generation_config.json).

3. Missing pipeline_tag or library_name

Why it matters: These fields enable the “Use this model” button, inference widgets, and filtering on the Hugging Face Hub.

Fix: Add them to the YAML front matter in your model card

yaml
Copy
---
pipeline_tag: text-generation
library_name: transformers
---

4. Missing base_model

Why it matters: This optional field establishes lineage—important for reproducibility, trust, and search filtering. It’s also used to automatically display fine-tuned relationships.

Recommended: Specify the base model name used for fine-tuning in the metadata:

yaml
Copy
---
base_model: org-name/base-model-name
---

For merged models:

yaml
Copy
---
base_model:
  - model_a
  - model_b
tags:
  - merge
---

5. Not setting base_model_relation

Why it matters: While Hugging Face tries to infer relationships (e.g., fine-tuned, quantized), being explicit helps avoid misclassification.

Recommended: Declare it in your metadata:

yaml
Copy
---
base_model: org-name/base-model-name
base_model_relation: finetune
---

Allowed relations include: finetune, quantized, adapter, and merge.

TL;DR

Pitfall	Why It Matters	Fix
chat_template	Chat UI and inference may break	Add chat_template.jinja file
eos_token	Infinite or malformed outputs	Define in config.json
pipeline_tag	Missing inference widget and filters	Add to model card metadata
library_name	UI and filtering issues	Add to model card metadata
base_model	Loss of model lineage	Add to metadata for traceability
base_model_relation	Misclassified model relationship	Set explicitly in metadata

Final Thoughts

Sharing a model on Hugging Face is more than uploading weights—it's about documentation, discoverability, and community trust. A little extra care with metadata and model cards goes a long way in making your model accessible and impactful.

Make your models easy to find, easy to run, and easy to understand.

💡 Tip: Deploy your Hugging Face models with one click to scalable, efficient endpoints ready for real production. Learn more in our previous posts – “Deploy Models from Hugging Face to Friendli Endpoints” and “Deploy Multimodal Models from Hugging Face to FriendliAI with Ease”.