Astro Starlight Troubleshooting Build Errors Tutorial

What You Are Learning

This tutorial helps you troubleshoot common Astro/Starlight problems.

• Install errors.
• Development server errors.
• Markdown and MDX errors.
• Content collection schema errors.
• Sidebar slug errors.
• Image and asset path errors.
• Deployment build failures.

The Debugging Workflow

Read the error message
  ↓
Find the file mentioned
  ↓
Check the recent change
  ↓
Test locally
  ↓
Run build
  ↓
Preview build
  ↓
Deploy after it works

Core Commands

npm install
npm run dev
npm run build
npm run preview

npm run build is the most important command before deployment because it catches many issues that development mode may not fully reveal.

Wrong Project Folder

Problem:
npm run dev says there is no package.json.

Likely cause:
You are not inside the Astro project folder.

Fix:
cd your-project-folder
npm run dev

MDX Parsing Errors

Common causes:
- Unclosed JSX tag
- Incorrect component import path
- Raw HTML that MDX dislikes
- Curly braces used accidentally
- Component name starts with lowercase letter

Broken Component Imports

Problem:
Cannot find module '../../components/Card.astro'

Check:
- Does the file exist?
- Is the relative path correct?
- Is the capitalization exact?
- Are you importing from the right folder?

Content Collection Schema Errors

Schema expects:
order: z.number()

But frontmatter has:
order: "first"

Fix:
order: 1

Missing Required Frontmatter

Schema requires:
title: z.string()
description: z.string()

Entry has:
---
title: "Markdown Basics"
---

Fix:
Add description.

Sidebar Slug Errors

File:
src/content/docs/lessons/markdown-basics.md

Sidebar slug:
lessons/markdown-basics

If the slug is wrong, the sidebar link may lead to a 404.

Image Path Errors

File:
public/images/map.png

Good:
![Map](/images/map.png)

Bad:
![Map](/public/images/map.png)
![Map](C:\Users\Ray\Desktop\map.png)

Build Works Locally but Fails Online

Check:
- File name capitalization
- Missing committed files
- Environment variables
- Build command
- Output directory
- Node version

Deployment Settings

Troubleshooting Checklist

[ ] Am I in the correct folder?
[ ] Did I run npm install?
[ ] Does npm run dev work?
[ ] Does npm run build work?
[ ] Does npm run preview work?
[ ] Are all files committed?
[ ] Are image paths correct?
[ ] Are sidebar slugs correct?
[ ] Are MDX tags closed?
[ ] Does frontmatter match the schema?

Simple Rule of Thumb

Fix local build first.
Then preview the built site.
Then deploy.
Do not debug deployment before the local build works.