# Appendix C: Troubleshooting and Glossary

Course: [Astro](https://www.devtutorials.ai/learn/astro) · Section: Appendix
Source: https://www.devtutorials.ai/learn/astro/appendix/troubleshooting-and-glossary

> Common Astro errors and problems with their causes and fixes, plus a one-line glossary of every term used in the course.

## Appendix C: Troubleshooting and Glossary

- Part 1 lists common problems: what you see, why it happens, and how to fix it.
- Part 2 explains the words used in the course, in one line each.

## Part 1: Troubleshooting

### Build and Compile Errors

<div className="tscroll">

| You see | Why | Fix |
|---|---|---|
| `Unable to render X. No valid renderer was found` | A `.tsx`/`.jsx` component without its framework | `npx astro add preact` (or react, vue...) |
| `<p> on line 4 is never closed` | Astro 7 needs every tag closed | Add `</p>`, `</div>`... |
| `getStaticPaths() function is required` | A `[param]` page that is static | Export `getStaticPaths()`, or make the page on demand |
| `No adapter installed` / "needs an adapter" | On-demand page, session, action or server island | `npx astro add node` (or your host) |
| `Cannot find module '../components/Card.astro'` | Wrong path or file name case | Check the folder and the exact spelling |
| `X data does not match the collection schema` | A post's frontmatter breaks the Zod schema | Read the field name in the message and fix the post |
| Missing environment variable | `astro:env` required a variable that is not set | Add it to `.env` locally, and to the host dashboard |

</div>

### Things That Do Not Work

<div className="tscroll">

| Problem | Likely cause | Fix |
|---|---|---|
| A framework button ignores clicks | No `client:*` directive | Add `client:load` or `client:visible` |
| `window is not defined` | Browser code ran on the server | Move it to a `<script>`, `useEffect`, or use `client:only` |
| A button works only on the first page | `<ClientRouter />` runs scripts once | Set up in `document.addEventListener("astro:page-load", ...)` |
| Styles do not reach a child component | Styles are scoped | Use `:global()` or pass a `class` prop |
| My `console.log` shows nothing | Looking in the wrong console | Frontmatter → terminal, `<script>` → browser DevTools |
| `Astro.session` is `undefined` | The page is static | Make the page on demand |
| A new post does not show on the live site | Static pages are built once | Rebuild, or use on-demand or live data |
| Links 404 on GitHub Pages | `base` is missing from links | Build links from `import.meta.env.BASE_URL` |
| An image is not found | Wrong relative path | Imports are relative to the file; `public/` paths start with `/` |

</div>

Stuck? Make the smallest page that still shows the problem. Half the time you find the cause while making it. The other half, it is the perfect example to share on the Astro Discord.

After changing `astro.config.mjs`, `content.config.ts` or `.env`, restart `npm run dev`. Some changes are only read at start-up.

## Part 2: Glossary

<div className="tscroll">

| Word | Meaning |
|---|---|
| Adapter | A plugin that lets on-demand pages run on a host (Node, Netlify, Vercel, Cloudflare) |
| Build | Turning `src/` into the finished site in `dist/` |
| Cache | A saved copy of a response, reused to answer faster |
| CDN | Servers around the world that hold copies of your site near visitors |
| Client directive | A `client:*` attribute that hydrates an island |
| Collection | A group of content (posts, authors) with a schema |
| Component | A reusable piece of UI in its own file |
| Container API | Renders an Astro component to HTML outside a site, for tests |
| Cookie | A small piece of text the browser stores and sends with requests |
| Endpoint | A route file that returns data (JSON, XML) instead of a page |
| Frontmatter | The code between the `---` lines of an `.astro` file, or the data at the top of a Markdown file |
| Hydration | Attaching JavaScript to server HTML so it becomes interactive |
| i18n | Internationalization: a site in more than one language |
| Integration | A plugin that adds features to Astro (`preact`, `sitemap`, `mdx`) |
| Island | One interactive component on a mostly static page |
| Layout | A component that wraps pages with shared HTML |
| Live collection | Content loaded on every request instead of at build time |
| Middleware | Code that runs before every on-demand request |
| On-demand rendering | Building a page on the server for each request (SSR) |
| Prefetch | Loading a page in the background before the click |
| Prerender | Building a page ahead of time, at build time (SSG) |
| Props | Values passed into a component |
| Route | A URL and the file that answers it |
| Schema | Rules for the shape of data, written with Zod |
| Server island | A component rendered on the server after the page, with `server:defer` |
| Session | Per-visitor data kept on the server, linked by a cookie |
| Slot | A placeholder where a component shows the content passed into it |
| SSG / SSR / CSR | Static site generation / server-side rendering / client-side rendering |
| View transition | An animation between two pages |
| Zod | The library Astro uses to describe and check data |

</div>

Forgot a word? Search this page with Ctrl+F (Cmd+F on a Mac).