Error Handling & Fallback Mechanisms
Relevant source files
The following files were used as context for generating this wiki page:
Scoutline uses a standardized error taxonomy and a sequence-based fallback system. The system normalizes errors from different web providers into a single internal representation. It implements automated recovery by rotating through available providers when transient or unsupported capability errors occur.
Sources: packages/scoutline/src/lib/errors.ts, packages/scoutline/src/lib/provider-fallback.ts
Error Hierarchy and Taxonomy
The core of the system is the ScoutlineError class. It extends the native Error to include metadata for retries and shell exit codes. Every provider-specific failure maps to a concrete subclass. This ensures that the CLI handles different failure modes consistently across all commands.
Base Error Class
ScoutlineError carries a machine-readable code, a statusCode for HTTP-related failures, and a retryable boolean. It also defines an exitCode which determines the process return value.
Sources: packages/scoutline/src/lib/errors.ts:6-25, packages/scoutline/tests/errors.test.js:33-45
Specialized Error Types
| Error Class | Code | Default Exit Code | Description |
|---|---|---|---|
ValidationError | VALIDATION_ERROR | 1 | Invalid user input or flag values. |
ConfigurationError | CONFIGURATION_ERROR | 3 | Missing API keys or environment variables. |
AuthError | AUTH_ERROR | 1 | Invalid credentials or 401 responses. |
QuotaError | QUOTA_ERROR | 1 | Rate limits reached or credits exhausted. |
TimeoutError | TIMEOUT_ERROR | 1 | Request exceeded specified duration. |
NetworkError | NETWORK_ERROR | 1 | Connectivity issues or DNS failures. |
UnsupportedCapabilityError | UNSUPPORTED_CAPABILITY | 1 | Provider lacks the requested feature. |
Sources: packages/scoutline/src/lib/errors.ts:50-200, packages/scoutline/tests/errors.test.js:63-150
Error Class Diagram
The following diagram illustrates the relationship between the base error class and its specialized descendants.
The diagram shows that all system errors inherit from ScoutlineError, ensuring standardized metadata access.
Sources: packages/scoutline/src/lib/errors.ts:6-200
Provider Fallback Logic
The fallback mechanism allows Scoutline to attempt a research task using multiple providers in a prioritized sequence. The engine continues to the next provider if the current one fails with a non-fatal error.
Fallback Execution Flow
The invokeWithFallback function manages the execution loop. It selects providers based on their configuration state and capability support.
- Identify Candidates: Filters the registry for providers that support the required capability (e.g., search, read).
- Configuration Check: Only providers with valid environment variables (e.g.,
TAVILY_API_KEY) enter the pool. - Iterative Execution: Invokes the first provider.
- Error Classification:
- If successful, it returns the result immediately.
- If a
ScoutlineErroroccurs, it checks if the error is "fallbackable" (transient network issues or unsupported options). - If the error is fatal (e.g.,
ConfigurationError), the loop terminates.
- Exhaustion: If all providers fail, the engine throws a combined error.
Sources: packages/scoutline/src/lib/provider-fallback.ts:10-50, packages/scoutline/src/lib/errors.ts:240-260
Fallback Sequence Diagram
The following diagram shows the interaction between the Command Invoker and the Fallback Manager.
The sequence demonstrates how transient failures trigger rotation while fatal configuration errors halt execution.
Sources: packages/scoutline/src/lib/provider-fallback.ts:15-60, packages/scoutline/tests/errors.test.js:250-270
Error Normalization and Redaction
Scoutline prevents the leakage of sensitive information through error envelopes. The formatErrorOutput utility prepares error data for public display by stripping internal metadata.
Redaction Rules
- Credentials: API keys and Authorization headers are removed from error messages and cause objects.
- Stack Traces: Internal file paths and line numbers are suppressed in the public JSON response.
- Response Bodies: Raw HTML or JSON bodies from providers (which might contain session tokens) are excluded.
Sources: packages/scoutline/src/lib/errors.ts:280-300, packages/scoutline/tests/errors.test.js:315-335
JSON Error Envelope
Programmatic consumers receive a consistent JSON structure regardless of the underlying failure.
{
"success": false,
"error": "Short descriptive message",
"code": "API_ERROR",
"statusCode": 503,
"help": "Suggestion for the user to try --provider or check keys"
}
Sources: packages/scoutline/tests/errors.test.js:345-360, packages/scoutline/tests/output-budget-t4.test.js:450-465
Conclusion
The error handling and fallback system provides a resilient interface for investigative research. By standardizing errors and automating provider rotation, Scoutline minimizes manual intervention during source failures. The strict redaction policy ensures that diagnostic information never compromises credential security.