Fix Bad Indentation Of A Mapping Entry Error In Astro

What Causes This Error?

The “bad indentation of a mapping entry” error in Astro occurs in your frontmatter section (the area between the triple dashes --- at the top of your .mdx files). This error has several potential causes:

1. Inconsistent Indentation

YAML (the format used in frontmatter) is extremely sensitive to indentation. Each level of nesting must use consistent spacing:

1
---
2
# Incorrect indentation
3
layout: ../layouts/BlogPost.astro
4
title: My Blog Post
5
  author: # This line has extra spaces
6
    name: John Doe
7
---

The correct version would align the indentation properly:

1
---
2
# Correct indentation
3
layout: ../layouts/BlogPost.astro
4
title: My Blog Post
5
author: # Properly aligned
6
    name: John Doe
7
---

2. Mixing Tabs and Spaces

One of the most common causes is mixing tabs and spaces in your indentation. YAML requires consistent use of either tabs or spaces (with spaces being the recommended approach):

1
---
2
layout: ../layouts/BlogPost.astro
3
title: My Blog Post
4
author:
5
  name: John Doe # This line uses a tab instead of spaces
6
  email: [email protected] # This line uses spaces
7
---

3. Special Characters in Strings

Unescaped special characters in your frontmatter strings can break the YAML parser:

1
---
2
title: 'My Page's Title' # The apostrophe breaks the string
3
---

How to Fix the Error

Solution 1: Fix Quotation Marks

If your error involves strings with special characters like apostrophes or quotes, you have several options:

1
---
2
# Option 1: Use double quotes for strings with apostrophes
3
title: "My Page's Title"
4

5
# Option 2: Use YAML's multiline string format
6
description: >-
7
    This is a long description that contains an apostrophe's and spans multiple lines without causing errors.
8

9

10
# Option 3: Remove quotes entirely for simple strings
11
simpleTitle: My Page Title
12
---

Solution 2: Standardize Indentation

Ensure all indentation in your frontmatter uses the same character type (preferably spaces) and the same number of spaces per level (typically 2 or 4):

1
---
2
meta:
3
    title: My Page
4
    description: This is my page
5
    social:
6
        image: ./social.jpg
7
        alt: Social image
8
---

Solution 3: Use a YAML Validator

For complex frontmatter, use an online YAML validator to check your syntax before running your Astro build:

1. Copy your frontmatter (without the triple dashes)
2. Paste it into a YAML validator like YAML Lint
3. Fix any errors highlighted by the validator

Solution 4: Check for Invisible Characters

Sometimes, invisible characters like zero-width spaces can sneak into your code, especially when copying from websites or documents:

1. Open your file in a code editor that can show invisible characters
2. Look for any unusual spacing or characters
3. Retype the problematic lines from scratch instead of copying/pasting

Common Examples and Their Fixes

Example 1: Lists in Frontmatter

Lists in YAML require consistent formatting:

1
---
2
# Incorrect
3
tags:
4
- astro
5
  - javascript # Wrong indentation for nested item
6
- css
7

8
# Correct
9
tags:
10
  - astro
11
  - javascript
12
  - css
13

14
# Also correct (alternative syntax)
15
tags: [astro, javascript, css]
16
---

Example 2: Complex Nested Objects

When working with deeply nested objects, maintain consistent indentation at each level:

1
---
2
# Correct complex nesting
3
project:
4
    details:
5
        client:
6
            name: Acme Corp
7
            contact:
8
                email: [email protected]
9
                phone: 555-1234
10
        timeline:
11
            start: 2025-01-01
12
            end: 2025-06-30
13
---

By understanding these common causes and solutions, you can quickly resolve the “bad indentation of a mapping entry” error in your Astro projects. Remember that YAML is strict about formatting, so consistent indentation and proper handling of special characters are essential for smooth development.

When in doubt, simplify your frontmatter structure or use a YAML validator to catch issues before they cause build errors. With these techniques, you’ll spend less time debugging and more time building amazing websites with AstroJS.