Troubleshooting Guide

This guide covers common issues you might encounter during development and their solutions.

Environment Setup Issues

Node.js Version Problems

Issue: Wrong Node.js version causing build failures or dependency issues.

Symptoms:

npm install fails with version warnings
Build process throws unexpected errors
Different behavior between local and CI

Solution:

# Check current version
node --version

# Switch to project version
nvm use  # or asdf local nodejs $(cat .nvmrc)

# For asdf users, set this environment variable
export ASDF_NODEJS_LEGACY_FILE_DYNAMIC_STRATEGY=latest_available

# Clean install dependencies
npm run fresh

Environment Variables Not Loading

Issue: Environment variables are undefined or not accessible.

Symptoms:

undefined values for environment variables
Server-side variables not accessible in client
Build failures related to missing config

Solutions:

Check file naming: Ensure .env.local exists (not .env.example)

Verify Astro config: Add variables to astro.config.mjs:

env: {
  schema: {
    SERVER_MY_SECRET: {
      context: "server",
      access: "secret",
    },
    PUBLIC_MY_VAR: {
      context: "client",
      access: "public",
    },
  },
},

Check variable naming: Server variables need SERVER_ prefix, client variables need PUBLIC_ prefix
Restart dev server after changing environment variables

Port Conflicts

Issue: Development server won’t start due to port conflicts.

Symptoms:

EADDRINUSE error on port 3000
Server starts but shows wrong content

Solution:

# Kill processes on port 3000
lsof -ti:3000 | xargs kill -9

# Or use different port
npm run dev -- --port 3001

Build and Development Issues

Server Island Rendering Errors

Issue: Mismatched server island rendering causing hydration errors.

Symptoms:

Console errors about server island mismatches
Components not hydrating correctly
Inconsistent rendering between server and client

Solution:

# Ensure ASTRO_KEY is set in .env.local
echo "ASTRO_KEY=your-secret-key-here" >> .env.local

# Restart development server
npm run dev

GraphQL Type Generation Failures

Issue: TypeScript errors about missing GraphQL types.

Symptoms:

Import errors for generated types
TypeScript compilation failures
Missing query type definitions

Solutions:

Run codegen: npm run codegen
Check GraphQL endpoint: Verify CAPI connection in .env.local
Verify query files: Ensure .cms.graphql files are properly formatted
Clear cache: Delete node_modules and reinstall

Hot Module Replacement (HMR) Not Working

Issue: Changes not reflecting in browser during development.

Symptoms:

Need to manually refresh browser
Styles not updating
Component changes not appearing

Solutions:

Check file extensions: Ensure proper .astro, .tsx, .ts extensions
Restart dev server: npm run dev
Clear browser cache: Hard refresh with Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
Check file watchers: Increase system file watcher limits if needed

Runtime Issues

Component Hydration Failures

Issue: Interactive components not working in browser.

Symptoms:

Buttons don’t respond to clicks
State changes don’t trigger updates
Console errors about hydration mismatches

Solutions:

Check client directives: Ensure proper client:load, client:visible, or client:idle usage
Verify component exports: Ensure proper default exports in .tsx components
Check for SSR/hydration mismatches: Ensure server and client render same content
Review error boundaries: Add proper error handling in components

CSS Styles Not Applying

Issue: Tailwind classes or custom styles not working.

Symptoms:

Components appear unstyled
Design tokens not resolving
Styles work in Storybook but not in app

Solutions:

Check Tailwind config: Verify tailwind.config.mjs includes all content paths
Verify design token imports: Check CSS imports in components
Check mode attributes: Ensure proper data-theme and data-mode attributes
Clear build cache: Delete dist/ and rebuild

Image Loading Problems

Issue: Images not displaying or loading slowly.

Symptoms:

Broken image placeholders
Slow image loading
Imgix parameters not working

Solutions:

Check image URLs: Verify Imgix domain configuration
Review image component: Ensure proper ImgixImage component usage
Check loading strategies: Verify loading="lazy" for below-fold images
Verify image formats: Ensure supported formats (WebP, AVIF, JPG)

Performance Issues

Slow Build Times

Issue: Build process takes excessively long.

Symptoms:

npm run build takes several minutes
CI/CD pipelines timing out
Local development builds slow

Solutions:

Analyze bundle: Use npm run analyze to identify large dependencies
Check dynamic imports: Ensure proper code splitting
Review image optimization: Check for unoptimized large images
Update dependencies: Ensure latest versions of build tools

Large Bundle Sizes

Issue: JavaScript bundles are too large.

Symptoms:

Slow page load times
High Lighthouse scores for performance
Large network requests

Solutions:

Run bundle analyzer: npm run analyze
Implement code splitting: Use dynamic imports for large components
Tree shake unused code: Review and remove unused dependencies
Optimize images: Use proper image formats and sizes

Deployment Issues

Ephemeral Environment Not Working

Issue: PR preview environments not deploying or accessible.

Symptoms:

404 errors on ephemeral URLs
Build succeeds but site not accessible
Wrong content showing on preview

Solutions:

Check branch naming: Ensure branch name follows alphanumeric + hyphen convention
Wait for deployment: Allow up to 5 minutes after GitHub Actions completion
Check GitHub Actions: Review build logs for errors
Verify environment variables: Ensure nonprod secrets are properly configured

Production Deployment Failures

Issue: Production deployments failing or showing errors.

Symptoms:

Build failures in GitHub Actions
500 errors on production site
Missing environment variables in production

Solutions:

Check GitHub Actions logs: Review detailed error messages
Verify production secrets: Ensure AWS Parameter Store configuration
Test production build locally: Run npm run build && npm run start:server
Check for environment-specific code: Ensure no hardcoded local values

Testing and Quality Issues

Accessibility Violations

Issue: Accessibility tests failing or violations detected.

Symptoms:

Axe DevTools showing violations
Screen reader navigation problems
Keyboard navigation not working

Solutions:

Review ARIA attributes: Ensure proper labeling and roles
Check semantic HTML: Use proper heading hierarchy and landmarks
Test keyboard navigation: Ensure all interactive elements are focusable
Run automated tests: Use Astro Dev Tools accessibility panel

Storybook Issues

Issue: Storybook not starting or components not rendering.

Symptoms:

Storybook build failures
Components showing as blank
Story controls not working

Solutions:

Check story files: Ensure proper .stories.tsx format
Verify component exports: Check default exports in component files
Review Storybook config: Check .storybook/ configuration files
Clear Storybook cache: Delete Storybook cache and restart

Getting Help

If you’re still experiencing issues after trying these solutions:

Search documentation: Check relevant guides in this documentation
Check recent changes: Review recent PRs that might have introduced issues
Ask the team: Post in #lp-frontend Slack channel with:
- Clear description of the problem
- Steps to reproduce
- Error messages or screenshots
- What you’ve already tried
Create an issue: For persistent bugs, create a GitHub issue with detailed reproduction steps

Useful Debugging Commands

# Check versions
node --version
npm --version

# Clear all caches
npm run fresh
rm -rf dist/

# Verbose logging
npm run dev:logger

# Build analysis
npm run analyze

# Check for type errors
npx tsc --noEmit

# Lint issues
npm run lint

# Check Astro configuration
npx astro check