The Agent Governance SDK is designed to be resilient, but errors can still occur, especially during initial setup or due to network issues. This guide details the types of errors the SDK can produce and provides strategies for handling them gracefully in your application.

​
Error Philosophy

​
Non-Blocking by Default

The track... methods are designed to be non-blocking and fail silently (logging an error to the console) to prevent monitoring issues from crashing your core application logic. You can track an event, and even if the SDK fails to process or send it, your application will continue running.

​
Critical Operations Throw

Operations that are critical to the SDK’s function, such as initialization (new AgentMonitor(...) with invalid config) and manual flushing (monitor.flush()), will throw exceptions that you should handle.

​
Graceful Degradation

If the SDK encounters persistent, unrecoverable errors (e.g., an invalid API key), it will log the error and effectively disable itself to avoid impacting your application’s performance.

​
Common Error Types

The SDK uses standard JavaScript Error objects, often with additional properties to provide more context.

​
ValidationError

This error is thrown by the AgentMonitor constructor if the provided configuration is invalid.
  • name: Always 'ValidationError'.
  • message: A summary of the validation failures. Example: "Invalid configuration: apiKey: is required; batchSize: must be less than 1000"
  • details: An array of objects detailing specific validation issues. Useful for programmatic error handling.
  • path: The configuration key that failed, e.g., ['batchSize']
  • message: The specific error message for that key.
Example: 
try {
  const monitor = new AgentMonitor({
    apiKey: '', // Invalid
    organizationId: 'your-org-id',
    batchSize: 9999 // Invalid
  });
} catch (error) {
  if (error.name === 'ValidationError') {
    console.error('Configuration Error:', error.message);
    console.error('Details:', error.details);
  }
}

​
NetworkError / HttpRequestError

This error is thrown by monitor.flush() or monitor.shutdown() if the SDK fails to send an event batch after all retries.
  • name: Typically 'HttpRequestError' or similar
  • message: Describes the failure, e.g., "Failed to send events after 3 attempts. Final error: HTTP 500: Internal Server Error"
  • statusCode: HTTP status code of the final request (optional)
  • cause: The underlying error object (optional)
Example: 
try {
  await monitor.flush();
} catch (error) {
  console.error('Failed to send monitoring data:', error.message);
}

​
Error Handling Strategies

​
In Your Application Code

Since track... methods don’t throw, focus on handling configuration and shutdown errors.
1

Handle Configuration Errors

Wrap the AgentMonitor constructor in a try…catch block. A ValidationError is a critical setup issue.
let monitor;
try {
monitor = new AgentMonitor({ ... });
} catch (error) {
console.error('Failed to initialize AgentMonitor. Monitoring will be disabled.', error);
monitor = createMockMonitor();
}
2

Handle Shutdown Errors

Ensure monitoring data is flushed on shutdown, but don’t block shutdown if flushing fails.
async function gracefulShutdown() {
console.log('Shutting down...');
try {
await monitor.shutdown();
console.log('Monitoring data flushed successfully.');
} catch (error) {
console.error('Could not flush all monitoring data during shutdown:', error.message);
}
process.exit(0);
}

process.on('SIGTERM', gracefulShutdown);
3

Monitor SDK Logs

In production, ensure your logging system:
  • Ingests logs from stdout/stderr
  • Alerts on logs with level: 'error' and prefix [AgentGovernance]
  • Flags frequent messages like “Failed to flush events”

​
Troubleshooting Based on Errors