Appendix C: Troubleshooting and Glossary
By Syncfusion®, Inc. · Last updated
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
| 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 |
Things That Do Not Work
| 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 / |
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
| 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 |
Forgot a word? Search this page with Ctrl+F (Cmd+F on a Mac).