Troubleshooting
Common issues and how to fix them.
Build Errors
Module not found errors
If you see errors like Cannot find module:
# Delete node_modules and reinstall
rm -rf node_modules
npm install TypeScript errors in site.ts
Ensure all required fields are present. Check the Configuration docs for the full schema.
Recipe initialization fails
Make sure you're using the correct recipe name:
# List available recipes
npm run init:recipe -- --help
# Use exact recipe name
npm run init:recipe -- --recipe=corporate Styling Issues
CSS variables not applying
CSS variables are defined in src/styles/global.css. Make sure:
- The variable name matches exactly (case-sensitive)
- You're using
var(--variable-name)syntax - The variable is defined in
:rootor a parent element
Dark mode colors not working
Dark mode uses [data-theme="dark"] selector. Check that:
- Your component has dark mode variants defined
- The
data-themeattribute is on<html>or<body>
Fonts not loading
Fonts are loaded via Google Fonts in Layout.astro. To use custom fonts:
- Add font files to
public/fonts/ - Define
@font-faceinglobal.css - Update
--font-primaryand--font-headingvariables
Component Issues
Navigation mega menu not working
The mega menu requires React hydration. Ensure:
client:loaddirective is on the Navigation component- Radix UI packages are installed (
@radix-ui/react-navigation-menu)
Logo not displaying
Check your site.ts logo configuration:
- text-only: Only needs
textfield - icon-text: Needs
src,svgIcon, oremoji - gradient-box: Needs
text(first character used)
Form not submitting
Check the browser console for errors. Common causes:
- Invalid
actionURL - CORS issues with external endpoints
- Missing required fields
Deployment Issues
404 errors on deployed site
For GitHub Pages or subfolder deployments, set the base in astro.config.mjs:
export default defineConfig({
site: 'https://username.github.io',
base: '/repo-name',
}); Sitemap URLs are wrong
Set the correct site URL in astro.config.mjs:
export default defineConfig({
site: 'https://yourdomain.com',
}); Assets not loading in production
Ensure paths are relative or use the base config. Avoid absolute paths like /images/logo.png if using a subfolder deployment.
Still Stuck?
If you can't find a solution:
- Check Astro documentation for framework-specific issues
- Search or open an issue on GitHub
- Review the source code for implementation details