homepage.dev

Troubleshooting Guide

Common issues and solutions for homepage.dev users

Troubleshooting Guide

This comprehensive guide helps you resolve common issues encountered while using homepage.dev. If you can't find a solution here, please contact our support team.

Quick Diagnostic Checklist

Before diving into specific issues, run through this quick checklist:

Login & Authentication Issues

Cannot Login to Account

Symptoms:

Solutions:

  1. Clear Browser Data:

    # Chrome: Ctrl/Cmd + Shift + Delete
# Select "Cookies and other site data" and "Cached images and files"
# Time range: "All time"

  2. Check Password:

    • Use "Forgot Password" to reset if uncertain
    • Ensure caps lock is not enabled
    • Try typing password in a text editor first to verify

  3. Disable Browser Extensions:

    • Open an incognito/private window
    • Try logging in without extensions active
    • If successful, identify problematic extension

  4. Check Network Configuration:

    // Network diagnostics
const networkTests = {
  dns: 'nslookup api.homepage.dev',
  connectivity: 'ping api.homepage.dev',
  firewall: 'Check corporate firewall settings',
  vpn: 'Try disabling VPN temporarily'
}

Two-Factor Authentication Problems

Symptoms:

Solutions:

  1. Time Synchronization:

    • Ensure device time is accurate
    • Authenticator apps require precise time sync
    • Check timezone settings on device

  2. Try Backup Codes:

    • Use one of your saved backup codes
    • Each backup code can only be used once
    • Generate new backup codes after using

  3. Reset MFA (if locked out):

    • Contact support with account verification
    • Provide recent login locations and devices
    • May require identity verification process

SSO Integration Issues

Symptoms:

Solutions:

  1. Verify SSO Configuration:

    <!-- Check SAML configuration -->
<EntityDescriptor entityID="homepage.dev">
  <SPSSODescriptor>
    <AssertionConsumerService 
      Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="https://api.homepage.dev/auth/saml/callback"
      index="0" />
  </SPSSODescriptor>
</EntityDescriptor>

  2. Contact IT Administrator:

    • Verify user permissions in identity provider
    • Check attribute mappings
    • Confirm certificate validity

Page & Navigation Issues

Pages Not Loading

Symptoms:

Solutions:

  1. Check Internet Speed:

    # Minimum requirements:
# - 1 Mbps for basic functionality
# - 5+ Mbps for optimal experience
# Test at: speedtest.net

  2. Browser-Specific Issues:

    • Chrome: Clear site data in Settings > Privacy and security
    • Firefox: Clear cookies and cache for homepage.dev
    • Safari: Enable JavaScript and disable content blockers

  3. Check Console Errors:

    // Open browser developer tools (F12)
// Look for errors in Console tab
// Common errors and meanings:

// Network errors
"Failed to fetch" → Connectivity or firewall issue
"CORS error" → Cross-origin request blocked
"404 Not Found" → Resource missing, may be temporary

// JavaScript errors  
"Script error" → Extension or content blocker interference
"Uncaught TypeError" → Browser compatibility issue

Real-Time Sync Problems

Symptoms:

Solutions:

  1. Check WebSocket Connection:

    // In browser console:
console.log(navigator.onLine) // Should return true

// Check WebSocket status in Network tab
// Look for WebSocket connection to realtime.homepage.dev

  2. Network Configuration:

    • Corporate firewalls may block WebSocket connections
    • VPNs can interfere with real-time features
    • Mobile networks may have connectivity issues

  3. Force Reconnection:

    • Refresh the page to re-establish connection
    • Switch tabs and return to force reconnect
    • Close and reopen browser if persistent

Bookmark Management Issues

Bookmarks Not Saving

Symptoms:

Solutions:

  1. Validate Bookmark Data:

    // Common validation issues:
const bookmarkValidation = {
  url: {
    required: true,
    format: 'Must be valid URL with http:// or https://',
    maxLength: 2048
  },
  title: {
    required: true,
    maxLength: 500,
    noHtml: true
  },
  description: {
    maxLength: 1000,
    noHtml: true
  }
}

  2. Check Storage Limits:

    • Free plan: 1,000 bookmarks per user
    • Pro plan: 10,000 bookmarks per user
    • Enterprise: Custom limits
    • Delete unused bookmarks if at limit

  3. URL Accessibility:

    • Ensure the URL is publicly accessible
    • Some intranet URLs may not be reachable for metadata
    • Try adding without automatic title/favicon detection

Import/Export Problems

Symptoms:

Solutions:

  1. File Format Issues:

    // Supported import formats:
{
  "supported_formats": [
    "HTML (Netscape bookmark format)",
    "JSON (homepage.dev format)", 
    "CSV (title, url, description, tags)",
    "Chrome bookmarks export",
    "Firefox bookmarks backup"
  ]
}

  2. File Size Limits:

    • Maximum import file size: 10MB
    • For larger files, split into smaller batches
    • Remove unnecessary metadata before import

  3. Character Encoding:

    • Ensure file is UTF-8 encoded
    • Avoid special characters in file names
    • Convert from other encodings if necessary

Search Not Working

Symptoms:

Solutions:

  1. Check Search Syntax:

    # Basic search
github

# Tag search
tag:development

# Category search  
category:"Development Tools"

# Combined search
react tag:tutorial category:Learning

  2. Index Refresh:

    • Search index updates may take a few minutes
    • Recently added bookmarks might not appear immediately
    • Try exact URL search if title search fails

  3. Clear Search Filters:

    • Remove active filters that might be limiting results
    • Check date range filters
    • Verify category and tag filters

Performance Issues

Slow Loading Times

Symptoms:

Solutions:

  1. Browser Optimization:

    // Performance diagnostics
const performanceCheck = {
  memoryUsage: performance.memory?.usedJSHeapSize,
  timing: performance.timing,
  resources: performance.getEntriesByType('resource')
}

// Clear browser data if memory usage exceeds 100MB

  2. Reduce Data Load:

    • Limit bookmarks per category (recommended: under 50)
    • Archive old or unused bookmarks
    • Use search instead of browsing large collections

  3. Check System Resources:

    • Close unnecessary browser tabs
    • Restart browser if memory usage is high
    • Check available device memory and storage

High Memory Usage

Symptoms:

Solutions:

  1. Browser Memory Management:

    # Chrome memory usage check:
# chrome://memory-redirect/

# Firefox memory usage:
# about:memory

  2. Optimization Steps:

    • Close unused tabs and windows
    • Disable unnecessary browser extensions
    • Clear browser cache and storage
    • Restart browser session

Mobile-Specific Issues

Mobile App Problems

Symptoms:

Solutions:

  1. App Updates:

    • Ensure latest app version is installed
    • Check app store for available updates
    • Enable automatic updates for future releases

  2. Mobile Browser Issues:

    // Mobile browser compatibility check
const mobileCompatibility = {
  iOS: {
    safari: '14.0+',
    chrome: '90.0+',
    firefox: '88.0+'
  },
  android: {
    chrome: '90.0+',
    firefox: '88.0+',
    samsung: '14.0+'
  }
}

  3. Network Optimization:

    • Use WiFi when possible for better performance
    • Mobile data may have slower sync times
    • Background app refresh affects real-time updates

Touch Interface Issues

Symptoms:

Solutions:

  1. Touch Calibration:

    • Restart device to reset touch interface
    • Clean screen to ensure proper touch detection
    • Remove screen protector temporarily to test

  2. Browser Settings:

    • Enable "Desktop Site" mode if mobile view has issues
    • Adjust zoom level to improve touch targets
    • Clear mobile browser cache and data

Integration Issues

Browser Extension Problems

Symptoms:

Solutions:

  1. Extension Permissions:

    // Required permissions for bookmarklet:
const requiredPermissions = {
  activeTab: true,
  storage: true,
  scripting: true,
  host: 'https://homepage.dev/*'
}

  2. Reinstall Extension:

    • Remove existing extension
    • Clear extension data
    • Reinstall from official browser store
    • Reconfigure settings

API Integration Issues

Symptoms:

Solutions:

  1. API Status Check:

    # Check API health
curl https://api.homepage.dev/v1/health

# Expected response:
{
  "status": "healthy",
  "version": "2.0.0",
  "timestamp": "2024-01-20T14:30:00Z"
}

  2. Authentication Issues:

    • Verify API key is valid and not expired
    • Check API key permissions and scopes
    • Regenerate API key if necessary

  3. Rate Limiting:

    // Check rate limit headers
const rateLimitHeaders = {
  'X-RateLimit-Limit': '1000',
  'X-RateLimit-Remaining': '999', 
  'X-RateLimit-Reset': '1640995200'
}

// Wait for reset time if rate limited

Data & Sync Issues

Data Loss or Corruption

Symptoms:

Solutions:

  1. Check Account Status:

    • Verify you're logged into correct account
    • Check if organization membership changed
    • Confirm data wasn't moved to different page/tab

  2. Data Recovery:

    // Check for recent backups
const backupOptions = {
  automatic: 'Daily backups (last 30 days)',
  export: 'Manual exports by user',
  support: 'Contact support for data recovery'
}

  3. Prevent Future Loss:

    • Regular manual exports of important data
    • Enable automatic backup notifications
    • Use version control for critical bookmark collections

Sync Conflicts

Symptoms:

Solutions:

  1. Manual Sync:

    • Refresh browser/app on all devices
    • Log out and log back in to force sync
    • Clear local cache to pull fresh data

  2. Conflict Resolution:

    // Sync conflict resolution priority:
const conflictResolution = {
  priority: [
    'Most recent timestamp wins',
    'User with edit permissions takes precedence', 
    'Merge non-conflicting changes',
    'Prompt user for manual resolution'
  ]
}

Error Messages & Codes

Common Error Messages

Error CodeMessageCauseSolution
AUTH001"Authentication failed"Invalid credentialsReset password or check username
AUTH002"Session expired"Login session timeoutLog in again
RATE001"Too many requests"Rate limit exceededWait and reduce request frequency
DATA001"Validation error"Invalid data formatCheck input format and retry
NET001"Network error"Connection issueCheck internet connection
PERM001"Permission denied"Insufficient permissionsContact admin or page owner

HTTP Status Codes

// HTTP error code meanings
const httpErrors = {
  400: 'Bad Request - Invalid data format',
  401: 'Unauthorized - Login required',
  403: 'Forbidden - Insufficient permissions', 
  404: 'Not Found - Resource does not exist',
  409: 'Conflict - Data conflict or duplication',
  429: 'Too Many Requests - Rate limit exceeded',
  500: 'Internal Server Error - Contact support',
  502: 'Bad Gateway - Temporary server issue',
  503: 'Service Unavailable - Maintenance mode'
}

Advanced Troubleshooting

Browser Developer Tools

Chrome DevTools:

// Useful debugging commands
console.clear() // Clear console
localStorage.clear() // Clear local storage
sessionStorage.clear() // Clear session storage

// Check for errors
window.addEventListener('error', (e) => {
  console.error('JavaScript error:', e.error)
})

// Network monitoring
window.addEventListener('beforeunload', () => {
  console.log('Page unloading - check for unsaved changes')
})

Firefox Developer Tools:

// Firefox-specific debugging
about:config // Advanced browser settings
about:support // Troubleshooting information
about:memory // Memory usage analysis

Network Diagnostics

Connection Testing:

# DNS resolution
nslookup homepage.dev
nslookup api.homepage.dev

# Connectivity test
ping homepage.dev
ping api.homepage.dev

# Port accessibility (if corporate network)
telnet api.homepage.dev 443
telnet realtime.homepage.dev 443

Corporate Network Issues:

// Common corporate restrictions
const corporateRestrictions = {
  websockets: 'May be blocked by firewall',
  cors: 'Proxy servers can interfere',
  ssl: 'Certificate validation issues',
  ports: 'Non-standard ports may be blocked'
}

Performance Profiling

Memory Usage Analysis:

// Memory usage monitoring
const memoryInfo = {
  used: performance.memory?.usedJSHeapSize,
  total: performance.memory?.totalJSHeapSize,
  limit: performance.memory?.jsHeapSizeLimit
}

if (memoryInfo.used > memoryInfo.total * 0.8) {
  console.warn('High memory usage detected')
}

Load Time Analysis:

// Performance timing analysis
const perfData = performance.getEntriesByType('navigation')[0]
const loadTime = perfData.loadEventEnd - perfData.loadEventStart
const domReady = perfData.domContentLoadedEventEnd - perfData.domContentLoadedEventStart

console.log(`Page load time: ${loadTime}ms`)
console.log(`DOM ready time: ${domReady}ms`)

Getting Additional Help

Before Contacting Support

Gather this information to help with troubleshooting:

  1. System Information:

    • Browser name and version
    • Operating system and version
    • Device type (desktop/mobile/tablet)
    • Screen resolution and zoom level

  2. Error Details:

    • Exact error message or description
    • Steps to reproduce the issue
    • When the issue first occurred
    • Whether it affects all users or just you

  3. Browser Console:

    • Copy any error messages from browser console (F12)
    • Include network errors from Network tab
    • Note any failed requests or resources

Contact Information

Email Support: support@homepage.dev

Live Chat: Available for Pro and Enterprise customers

Community Forum: forum.homepage.dev

Status Page: status.homepage.dev

Still need help? Our support team is here to assist you. Contact us at support@homepage.dev with your specific issue and we'll get back to you quickly.

We Value Your Privacy

We use cookies to enhance your experience, analyze site traffic, and provide personalized content. By clicking "Accept All", you consent to our use of cookies. You can customize your preferences or learn more in our Privacy Policy.

GDPR & ePrivacy Compliant