Troubleshooting & FAQ

Common issues, solutions, and frequently asked questions

Find solutions to common problems and answers to frequently asked questions.

Troubleshooting Guide

Build Failures

❌ Error: `Cannot find module '@tailwindcss/vite'`

Cause: Missing dev dependencies or incomplete installation

Solution:

rm -rf node_modules package-lock.json
npm install
npm run build

❌ Error: `Node version must be >= 22.12.0`

Cause: Incorrect Node.js version

Solution:

# Check current version
node --version

# Using nvm (recommended)
nvm install 22.12.0
nvm use 22.12.0

# Or download from nodejs.org

❌ Error: `ENOENT: no such file or directory, open 'dist/...'`

Cause: Build artifacts missing

Solution:

npm run check   # Verify no errors
npm run build   # Full rebuild
npm run preview # Test locally

Development Server Issues

❌ Error: `Port 3000 already in use`

Cause: Another process using the port

Solution:

# Use different port
npm run dev -- --port 3001

# Or kill existing process
# Windows:
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# macOS/Linux:
lsof -i :3000
kill -9 <PID>

❌ Hot reload not working

Cause: File watcher limit exceeded

Solution:

# macOS (increase file watcher limit)
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Or restart dev server
npm run dev

❌ Slow development server

Cause: Many files or large dependencies

Solution:

Check for large node_modules folder
Use SSD instead of HDD
Reduce number of watched files
Restart VS Code

Content Issues

Cause: Missing front matter or incorrect syntax

Solution:

---
title: "My Page"           # Required
description: "About page"  # Required
order: 3                   # Required (number)
icon: "book-open"          # Optional
---

Verify:

Front matter between --- markers
All required fields present
Proper YAML syntax (no missing colons)

❌ Search not indexing new pages

Cause: Pagefind not ran or stale cache

Solution:

# Full rebuild with search
npm run build   # Includes postbuild Pagefind step

# Or manually run Pagefind
npx pagefind --site dist

❌ Code blocks not displaying correctly

Cause: Markdown syntax error

Solution:

# Incorrect (missing language)
\`\`\`
code here
\`\`\`

# Correct
\`\`\`javascript
code here
\`\`\`

❌ Links returning 404

Cause: Incorrect route or page not found

Solution:

Verify file exists in src/content/docs/
Check path is correct
Use exact filenames (case-sensitive on Linux)

Examples:

# Correct (using slug)
[Link](/docs/getting-started)

# Correct (using filename)
[Link](/docs/installation)

# Incorrect
[Link](/docs/getting_started)  # Wrong separator
[Link](/docs/Getting-Started)  # Wrong case

Cause: Route mismatch

Solution:

Ensure current URL matches link exactly
Check slug field in front matter
Verify no trailing slashes in navigation

Styling Issues

❌ Sidebar text blurry or hard to read

Cause (Fixed in this update):

Missing z-index
Backdrop blur effects

Solution: Already fixed in DocsLayout.astro

❌ Mobile layout broken

Cause: Responsive classes not working

Solution:

Verify Tailwind CSS processed correctly
Check viewport meta tag in head
Clear browser cache

❌ Colors not changing after edit

Cause: CSS cache or Tailwind rebuild needed

Solution:

# Restart dev server
npm run dev

# Or hard refresh browser
Ctrl+Shift+R (Windows/Linux)
Cmd+Shift+R (macOS)

Deployment Issues

❌ Build fails in CI/CD

Cause: Environment differences

Solution:

# Ensure Node version matches
- uses: actions/setup-node@v4
  with:
    node-version: '22.12.0'

❌ Site works locally but not on host

Cause: Configuration or environment mismatch

Solution:

Check astro.config.mjs site URL
Verify environment variables set
Test with npm run build && npm run preview

❌ Docker build fails

Cause: Missing dependencies or incorrect base image

Solution:

# Rebuild from scratch
docker build --no-cache -t docs-site:latest .

# Check logs
docker build -t docs-site:latest . 2>&1 | tail -20

❌ Search works locally but not on production

Cause: Pagefind index not generated in build

Solution:

{
  "scripts": {
    "postbuild": "pagefind --site dist"
  }
}

Verify in package.json.

Frequently Asked Questions

Q: Can I use a different framework?

A: This is built on Astro. You can:

Modify components to use Vue/React/Svelte
Use Astro’s integrations for other frameworks
Replace styling with CSS-in-JS solution
See Astro docs

Q: How do I add user authentication?

A: Static sites don’t support traditional auth, but you can:

Use GitHub Pages private deployments
Add password protection via hosting provider
Use third-party auth service (Auth0, Supabase)
Serve behind authentication proxy

Q: Can I use a database?

A: Not directly (static site). Alternatives:

Use headless CMS (Contentful, Sanity)
Fetch data at build time
Use API for dynamic content
See Astro data fetching

Q: How do I add comments/discussions?

A: Use third-party solutions:

Giscus (GitHub Discussions)
Utterances (GitHub Issues)
Disqus
Commento

Q: Can I monitor analytics?

A: Yes, multiple options:

Google Analytics
Plausible
Fathom
Cloudflare Analytics

Q: How do I handle blog posts?

A: Use content collections:

Create src/content/blog/ directory
Add .md files with front matter
Query with getCollection('blog')
Create dynamic routes

Q: Can I preview changes before deploying?

A: Yes:

npm run build    # Build for production
npm run preview  # Preview locally
# Visit http://localhost:3000

Q: How do I redirect old URLs?

A: Using redirects middleware:

// src/middleware.ts
export const onRequest = defineMiddleware((context, next) => {
  const oldRoutes: Record<string, string> = {
    '/old-page': '/docs/new-page',
    '/docs/v1/api': '/docs/api-reference',
  };
  
  if (context.url.pathname in oldRoutes) {
    return context.redirect(oldRoutes[context.url.pathname]);
  }
  
  return next();
});

Q: How do I optimize for SEO?

A: Astro handles most automatically:

Semantic HTML generated
Meta tags for each page
Sitemap at /sitemap.xml
Open Graph tags (add to layout)

Add to src/layouts/DocsLayout.astro:

<meta name="og:title" content={title} />
<meta name="og:description" content={description} />
<meta name="og:image" content="https://yoursite.com/og-image.png" />

Q: How do I handle 404 errors?

A: Create src/pages/404.astro:

---
import DocsLayout from '../layouts/DocsLayout.astro';
---

<DocsLayout title="Page Not Found" description="404 - Page not found">
  <h1>Page Not Found</h1>
  <p>The page you're looking for doesn't exist.</p>
  <a href="/docs">Back to documentation</a>
</DocsLayout>

Q: How often should I update dependencies?

A: Best practices:

Monthly security updates
Quarterly feature updates
Use npm outdated to check
Test thoroughly before deploying

# Update patch versions (safe)
npm update

# Update major versions (requires testing)
npm install package@latest

Q: How do I backup my documentation?

Use Git for version control (recommended)
Export as static files from dist/
Use hosting provider backup features
Set up automated backups

# Backup current state
git tag v1.0.0-backup
git push origin v1.0.0-backup

Q: Can I use custom domains?

A: Yes, all hosting providers support it:

Update DNS records
Set custom domain in provider settings
Enable HTTPS/SSL certificate
See Deployment guide

Q: How do I measure performance?

A: Use multiple tools:

# Lighthouse audit
npm install -D lighthouse-ci

# Check build size
du -sh dist/

Tools:

Google Lighthouse
WebPageTest
GTmetrix
Vercel Analytics

Q: How do I handle image optimization?

A: Astro optimizes automatically:

---
import { Image } from 'astro:assets';
import myImage from '../assets/image.png';
---

<Image src={myImage} alt="Description" />

Q: Can I use markdown extensions?

A: Yes, via Remark plugins:

In astro.config.mjs:

markdown: {
  remarkPlugins: [
    'remark-gfm',              // Tables, strikethrough
    'remark-math',             // Math equations
  ],
}

Getting Help

Still stuck?

Check documentation - Search this guide
Review examples - Check existing pages
GitHub Issues - Search/open issue
Community - Ask in GitHub Discussions
Stack Overflow - Tag with astro, tailwindcss

Reporting bugs:

Minimal reproduction steps
Expected vs actual behavior
Error messages/logs
Environment info (Node version, OS)

Most issues are solved by:

Reading the error message carefully
Clearing cache: rm -rf node_modules package-lock.json && npm install
Restarting dev server: npm run dev
Checking the Astro docs

Troubleshooting & FAQ

Troubleshooting Guide

Build Failures

❌ Error: Cannot find module '@tailwindcss/vite'

❌ Error: Node version must be >= 22.12.0

❌ Error: ENOENT: no such file or directory, open 'dist/...'

Development Server Issues

❌ Error: Port 3000 already in use

❌ Hot reload not working

❌ Slow development server

Content Issues

❌ Page doesn’t appear in navigation

❌ Search not indexing new pages

❌ Code blocks not displaying correctly

Navigation Issues

❌ Links returning 404

❌ Active navigation link not highlighting

Styling Issues

❌ Sidebar text blurry or hard to read

❌ Mobile layout broken

❌ Colors not changing after edit

Deployment Issues

❌ Build fails in CI/CD

❌ Site works locally but not on host

❌ Docker build fails

❌ Search works locally but not on production

Frequently Asked Questions

Q: Can I use a different framework?

Q: How do I add user authentication?

Q: Can I use a database?

Q: How do I add comments/discussions?

Q: Can I monitor analytics?

Q: How do I handle blog posts?

Q: Can I preview changes before deploying?

Q: How do I redirect old URLs?

Q: How do I optimize for SEO?

Q: How do I handle 404 errors?

Q: How often should I update dependencies?

Q: How do I backup my documentation?

Q: Can I use custom domains?

Q: How do I measure performance?

Q: How do I handle image optimization?

Q: Can I use markdown extensions?

Getting Help

❌ Error: `Cannot find module '@tailwindcss/vite'`

❌ Error: `Node version must be >= 22.12.0`

❌ Error: `ENOENT: no such file or directory, open 'dist/...'`

❌ Error: `Port 3000 already in use`