Troubleshooting Sites

Solutions for common issues and problems with your sites.

Deployment Issues

Deployment Fails

Symptoms:

• Status shows "Failed"
• Site doesn't go live
• Red error indication

Check:

1. Read error message carefully
2. Check deployment logs
3. Note the specific error
4. Look for common causes

Common Causes:

Build Command Failed

• Syntax errors in code
• Missing dependencies
• Wrong build command
• Environment variables missing

Solutions:

• Run build command locally
• Check for TypeScript errors
• Verify dependencies installed
• Check environment variables

Output Directory Not Found

• Wrong directory name
• Directory name has typo
• Files in wrong location

Solutions:

• Check your output directory name
• Verify build created the folder
• Correct the path in settings
• Rebuild and deploy

File Upload Failed

• Connection interrupted
• Files too large
• Network timeout
• Too many files

Solutions:

• Use ZIP file instead
• Split into smaller uploads
• Check internet connection
• Retry the deployment
• Use different network

Build Takes Too Long

• Large dependencies
• Compilation slow
• Network timeout

Solutions:

• Optimize dependencies
• Use faster build tool
• Check network speed
• Consider pre-building

Blank Page After Deploy

Symptoms:

• Site loads but shows blank
• No content visible
• Browser console has errors

Check:

1. Open browser console (F12)
2. Look for error messages
3. Check Network tab
4. Review deployment logs

Causes and Solutions:

HTML Structure Issues

• Missing index.html
• Wrong HTML syntax
• Bad file structure

Solutions:

• Verify index.html exists
• Check HTML validity
• Ensure proper folder structure

Path Issues

• Absolute paths instead of relative
• Wrong path separators
• Missing file paths

Solutions:

• Use relative paths: ./styles.css
• Not absolute: /styles.css
• Check all file references
• Test locally first

Asset Loading Fails

• Images not loading
• CSS not applying
• JavaScript not running

Check:

1. Right-click → Inspect Element
2. Check Network tab
3. See which files fail
4. Note 404 errors

Solutions:

• Use relative paths
• Check file exists
• Verify file names (case sensitive)
• Check folder structure

JavaScript Errors

• Console shows red errors
• Scripts not running
• Events not firing

Solutions:

• Check browser console
• Look for error message
• Fix syntax errors locally
• Use source maps for debugging

Custom Domain Not Working

Symptoms:

• Domain shows error
• Takes long to load
• Connection refused
• SSL certificate error

Check:

1. Domain status in site settings
2. DNS propagation status
3. Browser console errors
4. SSL certificate status

Solutions:

DNS Not Propagated

• Verify DNS record added correctly
• Check CNAME value matches exactly
• Wait for propagation (up to 48 hours)
• Clear browser cache
• Try different browser/device

DNS Record Wrong

• CNAME value doesn't match
• Wrong record type
• Typo in domain name
• Wrong subdomain

Verify:

• Log into registrar
• Check CNAME record exists
• Verify value matches Nife's CNAME
• Confirm record type is CNAME
• Check TTL is reasonable

SSL Certificate Not Issued

• Still shows pending
• Browser warning about certificate
• HTTPS showing error

Solutions:

• Wait 5-10 minutes
• Check certificate status
• Clear browser cache
• Try incognito window
• Verify domain points to Nife

Domain Registered But Not Active

• Domain expired
• Not properly registered
• Registrar issue

Solutions:

• Verify domain is active
• Check expiration date
• Renew if expired
• Contact registrar support

Site Access Issues

Site Shows 404 Error

Symptoms:

• Page not found error
• URL works but shows 404
• All pages show 404

Causes:

Single Page Application (SPA) Routing

• React/Vue routing broken
• Direct URL doesn't work
• Refresh loses page

Solution:

• Configure server for SPA
• Contact Nife support
• Fallback all routes to index.html

File Not Found

• Page file doesn't exist
• Deleted accidentally
• Wrong file name

Solutions:

• Check file exists
• Verify file spelling
• Use correct path
• Redeploy with correct files

Site Too Slow

Symptoms:

• Takes long to load
• Poor performance
• Mobile especially slow
• Users complaining

Check:

1. Run performance test
2. Check file sizes
3. Review images
4. Look at JavaScript

Solutions:

• Optimize images (see Performance section)
• Minify code
• Reduce JavaScript
• Enable caching
• Use CDN effectively

Images Not Loading

Symptoms:

• Broken image icons
• alt text showing
• images folder missing
• certain images fail

Check:

1. Right-click broken image
2. Inspect element
3. Look at image URL
4. Check Network tab

Solutions:

• Use relative paths: ./images/photo.jpg
• Don't use absolute paths: /images/photo.jpg
• Check file names (case sensitive)
• Verify folder structure
• Ensure images were deployed

Links Not Working

Symptoms:

• Click link, page not found
• Navigation broken
• Some links work, some don't

Check:

1. Check link href attribute
2. Test link locally
3. Verify target file exists
4. Check path syntax

Solutions:

• Use relative links: ./about.html
• Avoid absolute: /about.html
• Use proper path separators
• Ensure files are deployed
• Check for typos

Performance Issues

Site Loads Very Slowly

Solutions:

1. Optimize images
2. Minify code
3. Enable compression
4. Lazy load assets
5. Reduce file size
6. See Performance section for details

High Bandwidth Usage

Check:

1. Large uncompressed images
2. Repeated file downloads
3. Inefficient caching
4. Video files

Solutions:

• Compress images
• Enable browser caching
• Optimize assets
• Use CDN effectively

Mobile Performance Poor

Solutions:

1. Reduce file sizes
2. Mobile-first design
3. Responsive images
4. Lazy loading
5. Minimize JavaScript

Security Issues

Browser Shows Security Warning

Symptoms:

• Red warning in address bar
• "Not secure" message
• Mixed content warnings

Causes:

HTTPS Not Enabled

• Using HTTP instead of HTTPS
• SSL not configured

Solutions:

• Wait for SSL to be issued
• Check domain status
• Clear browser cache
• Contact support if stuck

Mixed Content

• Some resources load over HTTP
• Should all be HTTPS

Solutions:

• Change all URLs to HTTPS
• Use protocol-relative URLs: //cdn.example.com
• Don't hardcode HTTP
• Check external resources

Rollback Issues

Can't Rollback

Symptoms:

• Rollback button disabled
• Rollback fails
• Old version not available

Solutions:

• Older versions may be deleted
• Can only rollback within retention period
• Deploy a fixed version instead
• Contact support for archived versions

Rollback Didn't Work

Symptoms:

• Rolled back but site still broken
• Wrong version restored
• Content still wrong

Solutions:

• Verify you rolled back to correct version
• Clear browser cache
• Wait for CDN propagation
• Try rolling back further

Deletion Issues

Can't Delete Site

Symptoms:

• Delete button disabled
• Deletion fails
• Site won't disappear

Solutions:

• May be limited to admins
• Check permissions
• Try clearing cache
• Contact site owner
• Contact support

Site Still Accessible After Deletion

Symptoms:

• Deleted but still online
• URL still works
• Takes time to remove

Solutions:

• CDN cache takes time to clear
• Wait 5-15 minutes
• Clear browser cache
• Try incognito window
• If persists, contact support

Export Issues

Export Failed

Symptoms:

• Export button doesn't work
• No file downloaded
• Error message appears

Solutions:

• Try different format (CSV vs JSON)
• Check browser popup blocker
• Try different browser
• Reload page and retry
• Contact support if continues

Export File Incomplete

Symptoms:

• Downloaded file is empty
• File is corrupted
• Data missing

Solutions:

• Try export again
• Use different format
• Check if all sites loaded first
• Manually note site details

General Troubleshooting Steps

Step 1: Gather Information

• Write down error message
• Note what you were doing
• Screenshot the issue
• Record time it occurred
• Note browser and OS

Step 2: Check Obvious Things

• Refresh page (Ctrl+F5)
• Clear browser cache
• Try different browser
• Try incognito window
• Check internet connection

Step 3: Review Logs

• Check deployment logs
• Look at browser console (F12)
• Review error messages
• Search online for error

Step 4: Try Solutions

• Follow guides above for your issue
• Test after each change
• Rollback if something breaks
• Document what worked

Step 5: Contact Support

If still not working:

1. Gather all information from Step 1
2. Test thoroughly first
3. Document attempts made
4. Contact support with:
   • Site name
   • Error message
   • Screenshots
   • Steps to reproduce
   • Browser info

Common Error Messages

Error	Cause	Solution
"Build failed"	Code error	Fix code, test locally
"404 Not Found"	File missing	Check file exists
"Connection timeout"	Upload interrupted	Retry deployment
"SSL pending"	Certificate not issued	Wait 5-10 minutes
"Domain not verified"	DNS not propagated	Wait or verify DNS
"Blank page"	HTML/Path issue	Check paths and HTML

Related Topics

• Creating Sites
• Managing Sites
• Custom Domains
• Performance and Optimization
• Version Control

Getting Additional Help

1. Check documentation - See related topics above
2. Search knowledge base - Find similar issues
3. Review error logs - Read detailed error messages
4. Try solutions - Systematically test fixes
5. Contact support - When stuck, get professional help