Error Handling & Network Resiliency
Relevant source files
The following files were used as context for generating this wiki page:
The Stacklet MCP server implements a structured error handling and network resiliency strategy to manage interactions with Stacklet Platform GraphQL APIs, AssetDB SQL services, and documentation endpoints. The system focuses on providing actionable feedback to LLMs and handling long-running or volatile network operations through timeouts, polling, and backoff mechanisms.
Annotated Error System
The project uses a specialized AnnotatedError class to wrap standard tool failures. This class provides structured guidance to the calling agent by combining the raw error with context-specific recovery steps.
AnnotatedError Structure
| Field | Description |
|---|---|
problem | A clear description of what went wrong. |
likely_cause | The most probable reason for the failure. |
next_steps | Actionable advice for the LLM to resolve the issue. |
original_error | Optional details from the underlying exception. |
Sources: stacklet/mcp/utils/error.py:12-25
The diagram shows how the AnnotatedError utility structures raw failures into user-facing guidance. Sources: stacklet/mcp/utils/error.py:27-33
Network Resiliency & Timeouts
The server manages network volatility using configurable timeouts and asynchronous polling for long-running operations like SQL queries and large dataset exports.
Asynchronous Job Polling
AssetDB and Platform tools utilize a polling mechanism for operations that exceed immediate HTTP response windows. The system tracks JobStatus transitions to determine success or failure.
- Terminal States:
FINISHED,FAILED,CANCELED. - Non-Terminal States:
QUEUED,STARTED,SCHEDULED.
Sources: stacklet/mcp/assetdb/models.py:26-44
Backoff and Retries
For dataset lookups, the server implements exponential backoff during polling to avoid overwhelming the API while waiting for job completion.
This sequence illustrates the polling loop and backoff logic used for long-running dataset operations. Sources: tests/test_tools_platform.py:539-565, tests/test_tools_assetdb.py:536-554
Tool-Specific Error Handling
AssetDB SQL Failures
AssetDB tools handle common SQL errors by suggesting simplifications or cache adjustments.
- Timeout Recovery: If a query times out (max 300s), the error guidance suggests requesting cached results via
max_age=-1or simplifying the SQL. - Parameter Validation: Invalid parameter values that do not match dropdown options result in 400 errors, prompting the user to check the source query for valid values.
- Data Source Resolution: If a named data source (e.g., "AssetDB") is missing, the tool provides specific instructions to verify configuration or permission settings.
Sources: stacklet/mcp/assetdb/tools.py:309-328, tests/test_tools_assetdb.py:615-635
GraphQL API Failures
Platform tools distinguish between GraphQL-level errors and HTTP transport errors.
- Validation Errors: Queries with unknown fields are rejected locally using schema introspection before reaching the server.
- Problem Objects: Users are encouraged to always query for the
problemsfield in connections, as it contains critical error messages alongside partial results. - HTTP vs GraphQL: The system parses valid GraphQL responses even if the backend erroneously returns a non-200 HTTP status code.
Sources: stacklet/mcp/platform/graphql_info.md:9-12, tests/test_tools_platform.py:284-307
Documentation Access Errors
If a requested document path is missing, the docs_read tool returns an error that prompts the agent to call docs_list to see available files. This prevents the agent from hallucinating platform features based on missing documentation.
Sources: tests/test_tools_docs.py:108-124
Security in Error Reporting
The server enforces strict data masking in error logs and responses to prevent credential leakage:
- Access tokens and identity tokens are never logged or exposed in error messages.
- The
Querymodel usesextra="ignore"to ensureapi_keyfields serialized by the backend are dropped during parsing. - Redash credentials are removed from alternate format URLs before being returned to the tool client.
Sources: CLAUDE.md:104-106, stacklet/mcp/assetdb/models.py:68-75, tests/test_tools_assetdb.py:321-331
Conclusion
Error handling in the Stacklet MCP server is designed for an AI-agent workflow, where failures are treated as prompts for recovery. By combining robust network polling with detailed annotated errors, the server maintains stability during complex cloud governance operations while ensuring sensitive credentials remain protected.