Troubleshooting Guide

Troubleshooting Guide

This guide covers common issues you might encounter when working with the BigIssue documentation site and their solutions.

Development Issues

Site Not Loading Locally

Problem: Running npm run dev but the site doesn’t load at http://localhost:4321

Solutions:

1. Check if the port is already in use:

   lsof -i :4321

2. Kill any processes using the port:

   kill -9 [PID]

3. Try running on a different port:

   npm run dev -- --port 4322

Build Failures

Problem: npm run build fails with TypeScript errors

Solutions:

1. Check TypeScript configuration:

   npx tsc --noEmit

2. Clear Astro cache:

   rm -rf node_modules/.astro
   npm run build

3. Reinstall dependencies:

   rm -rf node_modules package-lock.json
   npm install

Deployment Issues

CSS Not Loading on Deployed Site

Problem: Local site looks perfect but deployed site appears unstyled

Common Causes:

• Asset path configuration issues
• Build output problems
• CDN caching issues

Solutions:

1. Check Build Output:

   npm run build
   ls -la dist/

   Verify CSS files are present in the dist/ directory.

2. Clear Cloudflare Cache:

   • Go to Cloudflare Dashboard
   • Navigate to Caching → Purge Cache
   • Select “Purge Everything”

3. Verify Asset Paths: Check astro.config.mjs for correct site configuration:

   export default defineConfig({
     site: 'https://your-actual-site.pages.dev',
     // Remove base path for Cloudflare Pages
   });

4. Use Wrangler for Direct Deployment:

   npm install wrangler@latest --save-dev
   npm run build
   npx wrangler pages deploy ./dist --project-name your-project

GitHub Actions Failing

Problem: Deployment workflow fails in GitHub Actions

Check These:

1. Secrets Configuration:

   • CLOUDFLARE_API_TOKEN: Valid API token with correct permissions
   • CLOUDFLARE_ACCOUNT_ID: 32-character hexadecimal ID
   • CLOUDFLARE_PROJECT_NAME: Exact project name from Cloudflare Pages

2. Build Environment:

   • Node.js version compatibility (check workflow uses Node 18+)
   • Package-lock.json is committed and up to date

3. Common Error Messages:

   “Invalid API token”:

   • Regenerate API token with Cloudflare Pages:Edit permissions
   • Update GitHub secret

   “Project not found”:

   • Verify project name matches exactly in Cloudflare Pages
   • Check spelling and case sensitivity

Preview Deployments Not Working

Problem: Pull requests don’t generate preview URLs

Solutions:

1. Check Workflow Permissions: Ensure workflow has these permissions:

   permissions:
     contents: read
     deployments: write
     pull-requests: write

2. Verify Branch Configuration:

   • PR must target main branch
   • Feature branch should be pushed to origin

3. Check Action Logs:

   • Review GitHub Actions tab for detailed error messages
   • Look for Cloudflare API rate limiting issues

Content Issues

Links Not Working

Problem: Internal links return 404 errors

Solutions:

1. Check File Paths:

   • Ensure target files exist in src/content/docs/
   • Use correct relative paths or slugs

2. Update Navigation: Add new pages to astro.config.mjs sidebar configuration:

   sidebar: [
     {
       label: 'Guide',
       items: [
         { label: 'New Page', slug: 'new-page' },
       ],
     },
   ]

Images Not Displaying

Problem: Images show broken links or don’t load

Solutions:

1. Correct Image Paths:

   • Place images in src/assets/ for processed images
   • Use public/ for static images that don’t need processing

2. Image Imports:

   ![Alt text](../../assets/image.png)

3. Check File Extensions:

   • Use web-compatible formats (PNG, JPG, WebP, SVG)
   • Verify file names match exactly (case-sensitive)

Performance Issues

Slow Build Times

Problem: npm run build takes too long

Solutions:

1. Enable Parallel Processing: Check if your system supports parallel builds and optimize accordingly.

2. Image Optimization:

   • Compress large images before adding to repository
   • Use appropriate formats (WebP for photos, SVG for icons)

3. Clear Build Cache:

   rm -rf node_modules/.astro dist/
   npm run build

Getting Help

If you’re still experiencing issues:

1. Check GitHub Discussions for community support
2. Create an Issue using our bug report template
3. Review Recent Changes that might have caused the problem
4. Check Service Status:
   • GitHub Status
   • Cloudflare Status

Prevention Tips

• Always test changes locally before pushing
• Use feature branches for all changes
• Keep dependencies updated regularly
• Monitor deployment logs for warnings
• Test on multiple devices and browsers