Skip to main content

Complete Troubleshooting Guide

This guide covers all common issues, error messages, and troubleshooting steps for the hookVM platform and CLI tool.

CLI Authentication Issues​

Error: Authentication Required​

Error Message:

❌ Authentication failed
Please run "hookvm login" to authenticate with hookVM

Causes:

  • No authentication token stored
  • Authentication token expired
  • CLI not configured properly

Solutions:

  1. Re-authenticate:

    hookvm login

  2. Check authentication status:

    hookvm login status

  3. Clear and re-authenticate if token is corrupted:

    hookvm logout
    hookvm login

Error: Invalid or Expired Token​

Error Message:

Token: Invalid or expired
To re-authenticate, run: hookvm login

Causes:

  • Authentication token has expired
  • Token was revoked
  • Configuration file corruption

Solutions:

  1. Re-authenticate:

    hookvm login

  2. Clear configuration if issues persist:

    # Remove configuration file
    rm ~/.hookvm/config.json
    hookvm login

Browser Authentication Issues​

Error Message:

🌐 Opening browser for authentication...
⏳ Waiting for authentication in browser...
❌ Authentication timeout

Causes:

  • Browser not opening automatically
  • Authentication not completed within timeout (5 minutes)
  • Popup blocked by browser
  • Network connectivity issues

Solutions:

  1. Manual browser navigation:

    • Copy the authentication URL from CLI output
    • Open in browser manually
    • Complete authentication

  2. Check browser settings:

    • Ensure popups are allowed for hookvm.com
    • Try different browser
    • Disable browser extensions temporarily

  3. Network troubleshooting:

    • Check internet connectivity
    • Try from different network
    • Check corporate firewall settings

CLI Connection Issues​

Error: Invalid Endpoint URL​

Error Messages:

✗ Endpoint URL must use HTTP or HTTPS protocol
✗ Invalid endpoint URL format
✗ Invalid webhook endpoint URL format. Expected format: http://domain.com/endpoint-id

Causes:

  • Wrong URL protocol (using ws:// or other protocols)
  • Malformed URL structure
  • Invalid endpoint ID format

Solutions:

  1. Use correct URL format:

    # Correct formats
    hookvm listen https://hookvm.com/hooks/abc123-def456-ghi789-012345
    hookvm listen http://localhost:8080/hooks/abc123-def456-ghi789-012345

    # Incorrect formats
    hookvm listen ws://hookvm.com/hooks/endpoint  # Wrong protocol
    hookvm listen https://hookvm.com/endpoint     # Missing /hooks/ path

  2. Verify endpoint ID format:

    • Must be UUID format (8-4-4-4-12 hex characters)
    • Example: abc123-def456-ghi789-012345

Error: WebSocket Connection Failed​

Error Messages:

WebSocket error: Connection timeout
WebSocket disconnected: Connection refused  
The URL's scheme must be either 'http:' or 'https:'. 'ws:' is not allowed

Causes:

  • Server not reachable
  • Incorrect WebSocket URL configuration
  • Firewall blocking WebSocket connections
  • Server maintenance or downtime

Solutions:

  1. Check server connectivity:

    # Test basic connectivity
    ping hookvm.com
    curl https://hookvm.com

  2. Verify endpoint exists:

    • Check endpoint in web interface
    • Ensure endpoint is active and not deleted

  3. Network troubleshooting:

    • Try from different network
    • Check corporate firewall WebSocket policies
    • Test with different endpoint

  4. Clear CLI configuration:

    rm ~/.hookvm/config.json
    hookvm login

Error: Target URL Issues​

Error Messages:

✗ Invalid target URL format
✗ Target URL must use HTTP or HTTPS protocol

Causes:

  • Malformed target URL
  • Wrong protocol specification
  • URL syntax errors

Solutions:

  1. Use correct target URL format:

    # Correct formats
    hookvm listen <endpoint> --target http://localhost:3000
    hookvm listen <endpoint> --target https://api.example.com

    # Incorrect formats  
    hookvm listen <endpoint> --target localhost:3000      # Missing protocol
    hookvm listen <endpoint> --target ftp://localhost     # Wrong protocol

  2. Verify local server is running:

    # Check if local server is accessible
    curl http://localhost:3000

Web Interface Issues​

Login and Authentication​

Issue: Cannot log in to web interface

Symptoms:

  • Login form returns errors
  • Authentication loops back to login
  • Google Sign-in not working

Solutions:

  1. Check credentials:

    • Verify email and password
    • Use password reset if needed
    • Try Google Sign-in as alternative

  2. Browser troubleshooting:

    • Clear browser cookies and cache
    • Disable browser extensions
    • Try incognito/private browsing mode
    • Try different browser

  3. Network issues:

    • Check internet connectivity
    • Try from different network
    • Check if corporate firewall blocks access

Dashboard Loading Issues​

Issue: Dashboard not loading or blank page

Symptoms:

  • White/blank page after login
  • Partial page loading
  • JavaScript errors in console

Solutions:

  1. Browser troubleshooting:

    • Hard refresh (Ctrl+F5 or Cmd+Shift+R)
    • Clear browser cache
    • Enable JavaScript
    • Check browser console for errors

  2. Try different browser:

    • Test with Chrome, Firefox, Safari, or Edge
    • Update browser to latest version
    • Disable ad blockers temporarily

  3. Network troubleshooting:

    • Check internet stability
    • Try different network connection
    • Contact IT support for corporate networks

Data Not Loading​

Issue: Webhook events or data not appearing

Symptoms:

  • Empty event lists
  • Data not refreshing
  • Outdated information displayed

Solutions:

  1. Refresh and reload:

    • Manual page refresh
    • Check for auto-refresh settings
    • Verify time range filters

  2. Check permissions:

    • Verify user role and permissions
    • Confirm workspace access
    • Contact workspace administrator

  3. Verify webhook activity:

    • Check if webhooks are actually being sent
    • Test with CLI monitoring
    • Review external service configurations

Webhook Delivery Issues​

Outbound Webhook Failures​

Issue: Outbound webhooks not being delivered

Symptoms:

  • Events showing as failed in dashboard
  • Target servers not receiving webhooks
  • High failure rates in analytics

Common Error Responses:

Connection Refused (ECONNREFUSED):

Error: connect ECONNREFUSED 127.0.0.1:3000
  • Target server is down or not listening
  • Wrong port or host configuration
  • Firewall blocking connections

Timeout Errors:

Error: Request timeout
  • Target server taking too long to respond
  • Network latency issues
  • Server overload

HTTP Error Codes:

404 Not Found - Endpoint doesn't exist
401 Unauthorized - Authentication required  
403 Forbidden - Access denied
500 Internal Server Error - Target server error

Solutions:

  1. Verify target endpoint:

    # Test endpoint manually
    curl -X POST https://your-endpoint.com/webhook \
      -H "Content-Type: application/json" \
      -d '{"test": "data"}'

  2. Check target server:

    • Ensure server is running and accessible
    • Verify endpoint URL and path
    • Check server logs for errors

  3. Review webhook configuration:

    • Verify authentication headers
    • Check event type filters
    • Review retry policies

  4. Network troubleshooting:

    • Test from different networks
    • Check DNS resolution
    • Verify SSL/TLS certificates

Incoming Webhook Issues​

Issue: Incoming webhooks not appearing

Symptoms:

  • External services report successful delivery
  • No events showing in hookVM dashboard
  • CLI not receiving events

Solutions:

  1. Verify endpoint configuration:

    • Check endpoint URL in external service
    • Ensure endpoint is active
    • Verify authentication settings

  2. Test webhook delivery:

    # Test with curl
    curl -X POST https://hookvm.com/hooks/your-endpoint-id \
      -H "Content-Type: application/json" \
      -d '{"test": "webhook"}'

  3. Check external service settings:

    • Verify webhook URL is correct
    • Check event type selections
    • Review delivery settings

  4. Monitor with CLI:

    # Use CLI to debug
    hookvm listen https://hookvm.com/hooks/your-endpoint-id

Performance Issues​

Slow Dashboard Loading​

Issue: Dashboard or pages loading slowly

Solutions:

  1. Browser optimization:

    • Close unnecessary browser tabs
    • Clear browser cache
    • Disable heavy extensions

  2. Network optimization:

    • Check internet speed
    • Try wired connection instead of WiFi
    • Test from different location

  3. System resources:

    • Close other applications
    • Check available memory
    • Restart browser

High Memory Usage (CLI)​

Issue: CLI consuming excessive memory

Symptoms:

  • System becoming slow when CLI is running
  • Out of memory errors
  • CLI crashing unexpectedly

Solutions:

  1. Use console mode for high volume:

    # Disable UI for better performance
    hookvm listen <endpoint> --disable-ui

  2. Restart CLI periodically:

    • CLI automatically limits stored events to 1000
    • Restart if memory usage seems high
    • Use process monitoring tools

  3. System optimization:

    • Close other applications
    • Increase system memory if possible
    • Monitor system resources

Error Code Reference​

HTTP Status Codes​

2xx Success Codes:

  • 200 OK - Request successful
  • 201 Created - Resource created successfully
  • 204 No Content - Request successful, no response body

4xx Client Error Codes:

  • 400 Bad Request - Invalid request format
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Access denied
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded

5xx Server Error Codes:

  • 500 Internal Server Error - Server error
  • 502 Bad Gateway - Upstream server error
  • 503 Service Unavailable - Server temporarily unavailable
  • 504 Gateway Timeout - Upstream server timeout

CLI Exit Codes​

  • 0 - Success
  • 1 - General error (invalid arguments, connection failure, etc.)

Recovery Procedures​

Complete CLI Reset​

When to use: Multiple CLI issues, corrupted configuration

# 1. Clear configuration
rm ~/.hookvm/config.json

# 2. Reinstall CLI
npm uninstall -g @hookvm/cli
npm install -g @hookvm/cli

# 3. Re-authenticate
hookvm login

# 4. Verify installation
hookvm --version
hookvm login status

Web Interface Reset​

When to use: Persistent web interface issues

  1. Clear browser data:

    • Clear all cookies for hookvm.com
    • Clear localStorage and sessionStorage
    • Clear browser cache

  2. Reset browser:

    • Try incognito/private mode
    • Test with different browser
    • Update browser to latest version

  3. Network reset:

    • Try different network
    • Flush DNS cache
    • Reset network adapter

Getting Additional Help​

Diagnostic Information​

When contacting support, provide:

  1. CLI Information:

    hookvm --version
    node --version
    npm --version

  2. System Information:

    • Operating system and version
    • Browser type and version (for web issues)
    • Network environment (corporate/home/mobile)

  3. Error Details:

    • Complete error messages
    • Steps to reproduce issue
    • Screenshots of error conditions

Debug Logging​

Enable verbose logging when needed:

  1. CLI Debug Mode:

    # Set environment variable for debug output
    DEBUG=* hookvm listen <endpoint>

  2. Browser Developer Tools:

    • Open browser console (F12)
    • Check for JavaScript errors
    • Monitor network requests

Support Resources​

  1. Documentation: Review all sections for additional guidance
  2. Community: Check for known issues and solutions
  3. Support Ticket: Provide diagnostic information and detailed error descriptions

This comprehensive troubleshooting guide covers the most common issues encountered when using hookVM. Follow the solutions systematically and escalate to support when needed with appropriate diagnostic information.