Skip to main content

​
Troubleshooting Guide

Quick solutions to common problems you might encounter.

​
Database & Backend Issues

​
Data Not Loading

Cause: Environment variables not configured or Appwrite connection failed.Solution:
  1. Check .env file exists with correct values
  2. Verify Appwrite project ID is correct
  3. Check browser console for errors
  4. Ensure Appwrite platform includes your domain
VITE_APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
VITE_APPWRITE_PROJECT_ID=your_project_id
VITE_APPWRITE_DATABASE_ID=portfolio_db
Error: Access to XMLHttpRequest blocked by CORS policySolution:
  1. Go to Appwrite Console → Settings → Platforms
  2. Add your domain:
    • localhost (for development)
    • your-site.vercel.app (for production)
    • yourdomain.com (custom domain)
  3. Wait 1-2 minutes for changes to propagate
Error: Collection or database not foundSolution:
  1. Verify collection exists in Appwrite Console
  2. Check collection ID matches exactly (case-sensitive)
  3. Ensure database ID is correct in .env
Error: User is not authorizedSolution:
  1. Check collection permissions in Appwrite
  2. For public content: Add “Any” with Read permission
  3. For admin content: Add “Users” with all permissions
  4. See Permissions Guide

​
Image & Storage Issues

Possible Causes:
  • File too large (check bucket max size)
  • Wrong file format
  • Bucket permissions incorrect
Solution:
  1. Check file size (usually max 10MB)
  2. Use supported formats: jpg, png, gif, webp
  3. Verify bucket has “Users” create permission
  4. Check browser console for specific error
Possible Causes:
  • Bucket doesn’t have public read access
  • Image URL is incorrect
  • Image was deleted
Solution:
  1. Check bucket has “Any” read permission
  2. Test image URL directly in browser
  3. Re-upload the image if needed
Solution:
  1. Ensure file is .ttf, .otf, or .woff format
  2. Check file size < 5MB
  3. Verify custom-fonts bucket exists
  4. Check bucket permissions

​
Deployment Issues

Common Causes:
  • Missing dependencies
  • Environment variables not set
  • Syntax errors in code
Solution:
  1. Check Vercel build logs for specific error
  2. Run npm run build locally to test
  3. Ensure all env variables are set in Vercel
  4. Check for TypeScript/ESLint errors
Cause: SPA routing not configuredSolution: Add vercel.json to project root:
{
  "rewrites": [{ "source": "/(.*)", "destination": "/" }]
}
Solution:
  1. Variables must start with VITE_ prefix
  2. Redeploy after adding variables
  3. Check variables are set for correct environment (Production/Preview)
  4. Clear browser cache after redeploying

​
Admin Panel Issues

Solution:
  1. Verify Appwrite account exists
  2. Check email is verified in Appwrite
  3. Clear browser cookies and try again
  4. Check Appwrite Console for user status
Possible Causes:
  • Network error
  • Permission denied
  • Validation error
Solution:
  1. Check browser console for errors
  2. Verify you’re logged in
  3. Check all required fields are filled
  4. Try refreshing and re-saving
Solution:
  1. Clear browser cache
  2. Try a different browser
  3. Check for JavaScript errors in console
  4. Ensure all dependencies are installed
Solution:
  1. Wait 10-15 minutes for DNS propagation
  2. Verify DNS records are correct:
    • CNAME pointing to your domain
    • TXT record with verification token
  3. Check DNS with online tools (dnschecker.org)
  4. Ensure Cloudflare proxy is enabled (if using)
Solution:
  1. Check shortlink_analytics collection exists
  2. Verify collection permissions
  3. Test with incognito/private browsing
  4. Check browser console for errors

​
Shop & Payment Issues

Solution:
  1. Verify VITE_PAYPAL_CLIENT_ID is set
  2. Check PayPal Client ID is correct
  3. Ensure PayPal app is enabled
  4. Test with sandbox credentials first
Solution:
  1. Check orders collection exists with all attributes
  2. Verify collection permissions
  3. Check browser console for validation errors
  4. Ensure all required fields are provided

​
Performance Issues

Solutions:
  1. Optimize images before uploading (compress, resize)
  2. Reduce number of embeds per page
  3. Use lazy loading for images
  4. Check network tab for slow requests
  5. Consider CDN for static assets
Solutions:
  1. Clear browser cache
  2. Close unused browser tabs
  3. Check for memory leaks in console
  4. Reduce number of items per page in lists

​
Quick Diagnostic Steps

When something isn’t working:
1

Check Browser Console

Press F12 → Console tab. Look for red error messages.
2

Check Network Tab

Press F12 → Network tab. Look for failed requests (red).
3

Verify Environment

Ensure .env file exists and has correct values.
4

Check Appwrite Console

Verify collections, buckets, and permissions are set up.
5

Clear Cache

Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)

​
Getting Help

If you’re still stuck:
  1. Check the specific feature documentation for detailed setup steps
  2. Review Appwrite Console for database/storage issues
  3. Check Vercel logs for deployment issues
  4. Search error messages online for common solutions
Most issues are caused by missing environment variables, incorrect permissions, or CORS configuration. Always check these first!