10 Common LLMs.txt Mistakes and How to Fix Them

8 min readBest Practices

Heads up! These 10 mistakes account for 95% of llms.txt validation failures. Learn how to avoid them and ensure your file works perfectly with AI systems.

#1: Missing H1 Header

The Problem: Starting your file without a level 1 heading or using the wrong syntax.

❌ Wrong

My Website Documentation
========================

## About Us
- [Home](https://example.com): Welcome page

✅ Correct

# My Website Documentation

> Comprehensive documentation for our platform

## About Us
- [Home](https://example.com): Welcome page

Fix: Always start with exactly one # followed by a space and your site name.

#2: Missing or Malformed Blockquote

The Problem: Skipping the required blockquote summary or using incorrect syntax.

❌ Wrong

# My API Documentation

This is a summary of our API documentation.

## Endpoints
- [Users API](https://api.example.com/users)

✅ Correct

# My API Documentation

> Comprehensive API documentation for developers building integrations with our platform.

## Endpoints
- [Users API](https://api.example.com/users)

Fix: Use > at the start of each summary line. Keep it concise but descriptive.

#3: Using Relative URLs

The Problem: Using relative paths instead of complete URLs.

❌ Wrong

## Documentation
- [Getting Started](/docs/getting-started): Start here
- [API Guide](../api/guide.html): API reference
- [FAQ](faq): Frequently asked questions

✅ Correct

## Documentation
- [Getting Started](https://example.com/docs/getting-started): Start here
- [API Guide](https://example.com/api/guide): API reference
- [FAQ](https://example.com/faq): Frequently asked questions

Fix: Always use complete URLs starting with https:// or http://.

#4: No H2 Sections

The Problem: Missing the required H2 sections to organize your content.

❌ Wrong

# My Website

> Great content for developers

- [Home](https://example.com): Welcome page
- [About](https://example.com/about): About us
- [Contact](https://example.com/contact): Get in touch

✅ Correct

# My Website

> Great content for developers

## Main Pages
- [Home](https://example.com): Welcome page
- [About](https://example.com/about): About us

## Contact
- [Contact](https://example.com/contact): Get in touch

Fix: Group your links under logical H2 sections using ## syntax.

#5: Broken or Invalid URLs

The Problem: Including URLs that don't work or have typos.

Common URL Issues:

  • • Typos in domain names (exampl.com instead of example.com)
  • • Missing protocols (example.com/page instead of https://example.com/page)
  • • Links to development/localhost URLs
  • • URLs that return 404 or 500 errors
  • • Password-protected or private URLs

Fix: Test every URL before adding it. Use our validator to check for broken links.

Quick Fix Reference

MistakeQuick FixExample
Missing H1Add # Title at start# My Site
No blockquoteAdd > summary> Site description
Relative URLsUse full https:// URLshttps://example.com
No H2 sectionsGroup links under #### Documentation
Wrong link formatUse [Text](URL): Description[API](https://...): Guide

Other Common Mistakes

#6: Duplicate URLs

Including the same URL multiple times in different sections.

#7: File Too Large

Creating files larger than 500KB that may exceed AI context limits.

#8: Poor Link Descriptions

Using generic descriptions like "Click here" instead of descriptive text.

#9: Including Login-Required Pages

Linking to pages that require authentication or are behind paywalls.

#10: Inconsistent Formatting

Mixed spacing, inconsistent bullet points, or malformed Markdown.

Prevention Tips

  • Use our validator: Check your file with our free validator before publishing
  • Start with examples: Use our templates as a starting point
  • Test all links: Manually visit every URL to ensure it works
  • Keep it updated: Review and update your file regularly

Avoid These Mistakes Today

Use our free validator to check your llms.txt file and catch these common mistakes before they affect your AI visibility.