Common Issues

Common Issues

This page provides solutions to common problems you might encounter while working with nodecode-docs-astro.

Build Errors

Frontmatter Validation Failed

Symptom:

[ERROR] Frontmatter does not match schema

Cause: Invalid or missing required frontmatter fields

Solution:

1. Check that all required fields are present:

   ---
   title: Your Page Title      # Required
   description: Your page description  # Required
   ---

2. Verify field types are correct:

   • title must be a string
   • description must be a string
   • template must be “doc” or “splash” (if provided)

3. Check for syntax errors in YAML:

   • Ensure proper indentation
   • Quote strings with special characters
   • No tabs (use spaces only)

Content Collection Not Found

Symptom:

[ERROR] Collection "docs" does not exist

Cause: Missing or incorrect src/content/config.ts file

Solution:

1. Ensure src/content/config.ts exists and exports collections:

   import { defineCollection } from 'astro:content';
   import { docsSchema } from '@astrojs/starlight/schema';
   
   export const collections = {
     docs: defineCollection({ schema: docsSchema() }),
   };

2. Restart the development server after creating the config file

TypeScript Errors

Symptom:

Property 'title' does not exist on type...

Cause: TypeScript types not generated yet

Solution:

1. Run the type generation command:

   bun run check

2. Restart your IDE/editor to pick up new types

3. Ensure tsconfig.json includes content directory

Development Server Issues

Port Already in Use

Symptom:

[ERROR] Port 4321 is already in use

Solution:

1. Kill the process using the port:

   # Find the process
   lsof -i :4321
   
   # Kill it
   kill -9 <PID>

2. Or use a different port:

   bun run dev -- --port 3000

Hot Reload Not Working

Symptom: Changes to files don’t trigger automatic reload

Solution:

1. Check file is in watched directory (src/ or public/)
2. Restart the development server
3. Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
4. Check for file system permissions issues

CSS Changes Not Applying

Symptom: CSS changes don’t appear in the browser

Solution:

1. Verify custom CSS is imported in astro.config.mjs:

   starlight({
     customCss: [
       './src/styles/tokens.css',
       './src/styles/theme.css',
     ],
   })

2. Clear browser cache with hard reload

3. Check browser developer tools for CSS errors

4. Ensure CSS files are in src/styles/ directory

Content Issues

Page Not Appearing in Sidebar

Symptom: New page doesn’t show up in navigation

Solution:

1. Verify file is in correct location: src/content/docs/
2. Check frontmatter includes title field
3. Ensure sidebar configuration in astro.config.mjs:

   sidebar: [
     {
       label: 'Section Name',
       autogenerate: { directory: 'section-name' }
     }
   ]

4. Try setting explicit sidebar.order in frontmatter

Broken Internal Links

Symptom: Clicking internal link shows 404 error

Solution:

1. Use relative paths: /guides/getting-started not guides/getting-started
2. Don’t include .md extension in links
3. Verify target file exists in src/content/docs/
4. Check for typos in file paths

Images Not Loading

Symptom: Images show broken image icon

Solution:

1. Place images in public/ directory for static assets
2. Or use src/assets/ with import statements
3. Use correct path:
   • Public: /images/photo.jpg
   • Assets: import photo from '../assets/photo.jpg'
4. Verify file extension matches actual file

Deployment Issues

Build Fails in Production

Symptom: Build succeeds locally but fails in CI/CD

Solution:

1. Check Node.js version matches local environment
2. Verify all dependencies in package.json
3. Check for environment-specific code
4. Review build logs for specific errors
5. Test production build locally:

   bun run build
   bun run preview

Environment Variables Not Working

Symptom: Environment variables undefined in build

Solution:

1. Prefix with PUBLIC_ for client-side access:

   PUBLIC_API_URL=https://api.example.com

2. Access in code:

   import.meta.env.PUBLIC_API_URL

3. Set variables in deployment platform (Cloudflare Pages, Netlify, etc.)

Performance Issues

Slow Build Times

Symptom: Build takes longer than expected

Solution:

1. Reduce number of pages (split into multiple sites if very large)
2. Optimize images before adding to project
3. Use Bun instead of npm/yarn for faster builds
4. Clear .astro cache directory and rebuild
5. Check for expensive computations in components

Large Bundle Size

Symptom: JavaScript bundle is larger than expected

Solution:

1. Check for unnecessary imports
2. Use dynamic imports for heavy components:

   const Component = (await import('./Component.astro')).default;

3. Review Astro DevTools for bundle analysis
4. Consider code splitting strategies

Getting More Help

If you’re still experiencing issues:

1. Check the Astro documentation
2. Visit the Starlight documentation
3. Search existing GitHub issues
4. Ask in the Astro Discord community
5. Review this project’s README for specific setup instructions

Reporting Bugs

When reporting a bug, please include:

• Node.js and Bun versions
• Operating system
• Steps to reproduce
• Error messages (full stack trace if available)
• Expected vs actual behavior
• Relevant code snippets or configuration files