Troubleshooting

This guide helps you resolve common issues when using Sentinel Guard. Follow the diagnostic steps and solutions provided for each problem category.

Quick Diagnostics

Check System Status

Before diving into specific issues, verify your basic setup:

import { SentinelGuard } from "@uptimebeacon/sentinel-guard";
 
// Test basic configuration
const sentinel = new SentinelGuard({
	apiKey: process.env.SENTINEL_API_KEY!,
	baseUrl: process.env.SENTINEL_API_URL!,
	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
});
 
// Check if monitoring is active
console.log("Monitoring active:", sentinel.isMonitoringActive());
console.log("Error count:", sentinel.getErrorCount());

Environment Check

# Check Node.js version
node --version
 
# Check if environment variables are set
echo $SENTINEL_API_KEY
echo $SENTINEL_API_URL
echo $SENTINEL_MONITOR_API_KEY
 
# Check network connectivity
curl -I https://api.uptimebeacon.cloud

Installation Issues

Module Not Found Error

Problem: Cannot find module '@uptimebeacon/sentinel-guard'

Solutions:

1. Verify Installation

   npm list @uptimebeacon/sentinel-guard

2. Reinstall Package

   npm uninstall @uptimebeacon/sentinel-guard
   npm install @uptimebeacon/sentinel-guard

3. Clear Cache

   npm cache clean --force
   rm -rf node_modules
   npm install

4. Check Package.json

   {
   	"dependencies": {
   		"@uptimebeacon/sentinel-guard": "^1.2.2"
   	}
   }

TypeScript Compilation Errors

Problem: TypeScript compilation fails with type errors

Solutions:

1. Update TypeScript Version

   npm install --save-dev typescript@^5.0.0

2. Check tsconfig.json

   {
   	"compilerOptions": {
   		"target": "ES2020",
   		"module": "ES2020",
   		"moduleResolution": "node",
   		"esModuleInterop": true,
   		"allowSyntheticDefaultImports": true,
   		"strict": true
   	}
   }

3. Install Type Definitions

   npm install --save-dev @types/node

Permission Errors

Problem: Permission denied during installation

Solutions:

1. Use npx instead of global install

   npx @uptimebeacon/sentinel-guard

2. Configure npm prefix

   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
   source ~/.bashrc

3. Use sudo (not recommended)

   sudo npm install -g @uptimebeacon/sentinel-guard

Configuration Issues

Environment Variables Not Loading

Problem: Environment variables are undefined

Solutions:

1. Check .env File Location

   import dotenv from "dotenv";
   dotenv.config();
    
   console.log(
   	"API Key:",
   	process.env.SENTINEL_API_KEY?.substring(0, 10) + "...",
   );

2. Verify .env File Format

   # Correct format
   SENTINEL_API_KEY=your-api-key-here
   SENTINEL_API_URL=https://api.uptimebeacon.cloud
   SENTINEL_MONITOR_API_KEY=your-monitor-api-key-here
   
   # Incorrect format (avoid)
   SENTINEL_API_KEY = "your-api-key-here"  # No spaces, no quotes

3. Load Environment Variables Explicitly

   import { config } from "dotenv";
   config({ path: ".env" });

Invalid Configuration Error

Problem: Configuration validation fails

Solutions:

1. Validate Configuration

   function validateConfig(config: any) {
   	const required = ["apiKey", "baseUrl", "monitorApiKey"];
    
   	for (const field of required) {
   		if (!config[field]) {
   			throw new Error(`Missing required field: ${field}`);
   		}
   	}
    
   	if (typeof config.timeout !== "undefined" && config.timeout < 1000) {
   		throw new Error("Timeout must be at least 1000ms");
   	}
   }
    
   const config = {
   	apiKey: process.env.SENTINEL_API_KEY!,
   	baseUrl: process.env.SENTINEL_API_URL!,
   	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
   };
    
   validateConfig(config);

2. Check URL Format

   // Correct URL format
   const baseUrl = "https://api.uptimebeacon.cloud";
    
   // Incorrect formats
   const wrongUrl1 = "api.uptimebeacon.cloud"; // Missing protocol
   const wrongUrl2 = "https://api.uptimebeacon.cloud/"; // Trailing slash

Authentication Issues

Authentication Error (401)

Problem: AuthenticationError: Authentication failed

Solutions:

1. Verify API Keys

   // Check if API keys are correct
   console.log("API Key length:", process.env.SENTINEL_API_KEY?.length);
   console.log(
   	"Monitor API Key length:",
   	process.env.SENTINEL_MONITOR_API_KEY?.length,
   );
    
   // API keys should be properly formatted
   if (!process.env.SENTINEL_API_KEY?.startsWith("ub_")) {
   	console.error("Invalid API key format");
   }

2. Test Authentication

   import {
   	SentinelGuard,
   	AuthenticationError,
   } from "@uptimebeacon/sentinel-guard";
    
   const sentinel = new SentinelGuard({
   	apiKey: process.env.SENTINEL_API_KEY!,
   	baseUrl: process.env.SENTINEL_API_URL!,
   	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
   });
    
   try {
   	await sentinel.sendHeartbeat({ status: "ONLINE" });
   	console.log("Authentication successful");
   } catch (error) {
   	if (error instanceof AuthenticationError) {
   		console.error("Authentication failed - check your API keys");
   	}
   }

3. Check API Key Permissions

   • Verify keys are active in UptimeBeacon dashboard
   • Ensure keys have correct permissions
   • Check if keys are for the correct environment

Invalid Monitor API Key

Problem: Monitor-specific authentication fails

Solutions:

1. Verify Monitor Configuration

   // Check monitor API key format
   if (!process.env.SENTINEL_MONITOR_API_KEY?.startsWith("mon_")) {
   	console.error("Invalid monitor API key format");
   }

2. Test Monitor Access

   // Test with minimal heartbeat
   try {
   	const response = await sentinel.sendHeartbeat({
   		status: "ONLINE",
   		metadata: { test: true },
   	});
   	console.log("Monitor access successful");
   } catch (error) {
   	console.error("Monitor access failed:", error.message);
   }

Network Issues

Connection Timeout

Problem: NetworkError: Request timeout

Solutions:

1. Increase Timeout

   const sentinel = new SentinelGuard({
   	apiKey: process.env.SENTINEL_API_KEY!,
   	baseUrl: process.env.SENTINEL_API_URL!,
   	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
   	timeout: 30000, // 30 seconds
   });

2. Test Network Connectivity

   # Test API endpoint
   curl -I https://api.uptimebeacon.cloud
    
   # Test with timeout
   curl --connect-timeout 10 https://api.uptimebeacon.cloud

3. Configure Proxy (if needed)

   // For corporate networks
   const sentinel = new SentinelGuard({
   	apiKey: process.env.SENTINEL_API_KEY!,
   	baseUrl: process.env.SENTINEL_API_URL!,
   	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
   	// Additional proxy configuration may be needed
   });

DNS Resolution Issues

Problem: Cannot resolve API hostname

Solutions:

1. Check DNS Resolution

   nslookup api.uptimebeacon.cloud
   dig api.uptimebeacon.cloud

2. Test Alternative DNS

   # Use Google DNS
   nslookup api.uptimebeacon.cloud 8.8.8.8

3. Configure DNS in Code

   // Use IP address if DNS fails (temporary solution)
   const sentinel = new SentinelGuard({
   	apiKey: process.env.SENTINEL_API_KEY!,
   	baseUrl: process.env.SENTINEL_API_URL!,
   	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
   });

Database Connection Issues

Prisma Connection Error

Problem: Database monitoring fails

Solutions:

1. Test Prisma Connection

   import { PrismaClient } from "@prisma/client";
    
   const prisma = new PrismaClient();
    
   try {
   	await prisma.$connect();
   	console.log("Prisma connected successfully");
    
   	// Test query
   	await prisma.$queryRaw`SELECT 1`;
   	console.log("Prisma query successful");
    
   	sentinel.setPrismaClient(prisma);
   } catch (error) {
   	console.error("Prisma connection failed:", error);
   }

2. Check Database URL

   // Verify database URL format
   const dbUrl = process.env.DATABASE_URL;
   console.log("Database URL:", dbUrl?.substring(0, 20) + "...");
    
   if (!dbUrl) {
   	console.error("DATABASE_URL not set");
   }

3. Test Database Access

   # Test PostgreSQL connection
   psql $DATABASE_URL -c "SELECT 1"
    
   # Test MySQL connection
   mysql -u user -p -h host -e "SELECT 1"

Redis Connection Error

Problem: Redis monitoring fails

Solutions:

1. Test Redis Connection

   import { createClient } from "redis";
    
   const redis = createClient({
   	url: process.env.REDIS_URL,
   });
    
   try {
   	await redis.connect();
   	console.log("Redis connected successfully");
    
   	// Test ping
   	const pong = await redis.ping();
   	console.log("Redis ping:", pong);
    
   	sentinel.setRedisClient(redis);
   } catch (error) {
   	console.error("Redis connection failed:", error);
   }

2. Check Redis Configuration

   // Debug Redis URL
   const redisUrl = process.env.REDIS_URL;
   console.log("Redis URL:", redisUrl?.substring(0, 20) + "...");
    
   // Test different connection methods
   const redis = createClient({
   	socket: {
   		host: "localhost",
   		port: 6379,
   	},
   });

3. Test Redis Server

   # Test Redis server
   redis-cli ping
    
   # Check Redis logs
   redis-cli monitor

Performance Issues

High Latency Warnings

Problem: Performance degradation alerts

Solutions:

1. Analyze Performance Metrics

   class PerformanceAnalyzer {
   	private metrics: number[] = [];
    
   	addMetric(latency: number) {
   		this.metrics.push(latency);
   		if (this.metrics.length > 100) {
   			this.metrics.shift();
   		}
   	}
    
   	getStats() {
   		if (this.metrics.length === 0) return null;
    
   		const sorted = [...this.metrics].sort((a, b) => a - b);
   		return {
   			average:
   				this.metrics.reduce((a, b) => a + b) / this.metrics.length,
   			median: sorted[Math.floor(sorted.length / 2)],
   			p95: sorted[Math.floor(sorted.length * 0.95)],
   			min: sorted[0],
   			max: sorted[sorted.length - 1],
   		};
   	}
   }

2. Monitor System Resources

   function logSystemMetrics() {
   	const usage = process.memoryUsage();
   	const cpu = process.cpuUsage();
    
   	console.log("Memory:", {
   		rss: Math.round(usage.rss / 1024 / 1024) + "MB",
   		heapUsed: Math.round(usage.heapUsed / 1024 / 1024) + "MB",
   		heapTotal: Math.round(usage.heapTotal / 1024 / 1024) + "MB",
   	});
    
   	console.log("CPU:", {
   		user: cpu.user,
   		system: cpu.system,
   	});
   }

3. Optimize Database Queries

   // Monitor slow queries
   const slowQueryThreshold = 1000; // 1 second
    
   async function monitoredQuery<T>(
   	name: string,
   	query: () => Promise<T>,
   ): Promise<T> {
   	const start = Date.now();
    
   	try {
   		const result = await query();
   		const duration = Date.now() - start;
    
   		if (duration > slowQueryThreshold) {
   			console.warn(`Slow query detected: ${name} took ${duration}ms`);
   		}
    
   		return result;
   	} catch (error) {
   		console.error(`Query failed: ${name}`, error);
   		throw error;
   	}
   }

Monitoring Issues

Heartbeats Not Sending

Problem: No data appearing in dashboard

Solutions:

1. Check Monitoring Status

   console.log("Monitoring active:", sentinel.isMonitoringActive());
   console.log("Error count:", sentinel.getErrorCount());
    
   // Test manual heartbeat
   try {
   	const response = await sentinel.sendHeartbeat({
   		status: "ONLINE",
   		metadata: { test: true },
   	});
   	console.log("Manual heartbeat:", response);
   } catch (error) {
   	console.error("Manual heartbeat failed:", error);
   }

2. Debug Heartbeat Intervals

   let heartbeatCount = 0;
    
   const originalSendHeartbeat = sentinel.sendHeartbeat;
   sentinel.sendHeartbeat = async function (data) {
   	heartbeatCount++;
   	console.log(`Heartbeat #${heartbeatCount}:`, data);
   	return originalSendHeartbeat.call(this, data);
   };

3. Check Network Connectivity

   // Test API endpoint directly
   async function testApiEndpoint() {
   	try {
   		const response = await fetch(process.env.SENTINEL_API_URL!);
   		console.log("API Status:", response.status);
   	} catch (error) {
   		console.error("API unreachable:", error);
   	}
   }

Monitoring Stops Unexpectedly

Problem: Monitoring becomes inactive

Solutions:

1. Monitor Error Count

   setInterval(() => {
   	const errorCount = sentinel.getErrorCount();
   	if (errorCount > 0) {
   		console.warn(`Current error count: ${errorCount}`);
   	}
    
   	if (!sentinel.isMonitoringActive()) {
   		console.error("Monitoring stopped! Restarting...");
   		sentinel.startMonitoring({
   			interval: 30000,
   			maxConsecutiveErrors: 5,
   		});
   	}
   }, 60000);

2. Implement Error Recovery

   class ResilientMonitor {
   	private sentinel: SentinelGuard;
   	private restartCount = 0;
    
   	constructor() {
   		this.sentinel = new SentinelGuard({
   			apiKey: process.env.SENTINEL_API_KEY!,
   			baseUrl: process.env.SENTINEL_API_URL!,
   			monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
   		});
   	}
    
   	startMonitoring() {
   		this.sentinel.startMonitoring({
   			interval: 30000,
   			maxConsecutiveErrors: 3,
   		});
    
   		// Check every minute
   		setInterval(() => {
   			if (!this.sentinel.isMonitoringActive()) {
   				this.restartCount++;
   				console.log(
   					`Restarting monitoring (attempt ${this.restartCount})`,
   				);
    
   				this.sentinel.startMonitoring({
   					interval: 30000,
   					maxConsecutiveErrors: 3,
   				});
   			}
   		}, 60000);
   	}
   }

Error Handling

Unhandled Promise Rejections

Problem: Application crashes on monitoring errors

Solutions:

1. Implement Global Error Handling

   process.on("unhandledRejection", (reason, promise) => {
   	console.error("Unhandled Rejection at:", promise, "reason:", reason);
    
   	// Don't exit process, just log
   	// process.exit(1);
   });
    
   process.on("uncaughtException", (error) => {
   	console.error("Uncaught Exception:", error);
    
   	// Graceful shutdown
   	sentinel.stopMonitoring();
   	process.exit(1);
   });

2. Wrap Monitoring in Try-Catch

   async function safeMonitoring() {
   	try {
   		sentinel.startMonitoring({
   			interval: 30000,
   			maxConsecutiveErrors: 5,
   		});
   	} catch (error) {
   		console.error("Monitoring error:", error);
    
   		// Retry after delay
   		setTimeout(safeMonitoring, 10000);
   	}
   }

Environment-Specific Issues

Docker Container Issues

Problem: Monitoring fails in Docker

Solutions:

1. Check Environment Variables

   # Dockerfile
   ENV SENTINEL_API_KEY=""
   ENV SENTINEL_API_URL=""
   ENV SENTINEL_MONITOR_API_KEY=""

2. Test Network Connectivity

   # Inside container
   curl -I https://api.uptimebeacon.cloud
    
   # Check DNS resolution
   nslookup api.uptimebeacon.cloud

3. Debug Container Startup

   // Add startup diagnostics
   console.log("Container starting...");
   console.log("Environment:", process.env.NODE_ENV);
   console.log("API URL:", process.env.SENTINEL_API_URL);
   console.log("Network test...");

Production Environment Issues

Problem: Works in development but fails in production

Solutions:

1. Environment Comparison

   function diagnoseEnvironment() {
   	console.log("Environment Diagnostics:");
   	console.log("Node version:", process.version);
   	console.log("Platform:", process.platform);
   	console.log("Architecture:", process.arch);
   	console.log("Memory:", process.memoryUsage());
   	console.log("Environment:", process.env.NODE_ENV);
   }

2. Test Production Configuration

   // Use different configurations for different environments
   const config = {
   	apiKey: process.env.SENTINEL_API_KEY!,
   	baseUrl: process.env.SENTINEL_API_URL!,
   	monitorApiKey: process.env.SENTINEL_MONITOR_API_KEY!,
   	timeout: process.env.NODE_ENV === "production" ? 30000 : 10000,
   	retryConfig: {
   		maxRetries: process.env.NODE_ENV === "production" ? 5 : 3,
   		baseDelay: 2000,
   		backoffMultiplier: 2,
   	},
   };

Getting Help

Debug Information Collection

Before seeking help, collect this information:

function collectDebugInfo() {
	return {
		// System information
		nodeVersion: process.version,
		platform: process.platform,
		arch: process.arch,
 
		// Package information
		sentinelVersion: require("@uptimebeacon/sentinel-guard/package.json")
			.version,
 
		// Configuration (without sensitive data)
		config: {
			hasApiKey: !!process.env.SENTINEL_API_KEY,
			hasBaseUrl: !!process.env.SENTINEL_API_URL,
			hasMonitorApiKey: !!process.env.SENTINEL_MONITOR_API_KEY,
			apiKeyFormat: process.env.SENTINEL_API_KEY?.substring(0, 3) + "...",
		},
 
		// Monitoring status
		monitoringActive: sentinel.isMonitoringActive(),
		errorCount: sentinel.getErrorCount(),
 
		// System resources
		memory: process.memoryUsage(),
		uptime: process.uptime(),
	};
}

Support Channels

If you encounter installation issues not covered here:

1. Check the GitHub Issues 
2. Check the complete documentation for solutions
3. Contact support through UptimeBeacon.cloud

Common Solutions Summary

Remember to check the logs for specific error messages and stack traces, as they often provide the most direct path to resolution.