Error code system-Cloud Monitor(CMS)-阿里云帮助中心

Overview

UModel high-level APIs use a layered, structured error handling system that supports response status management, retry policies, and clear error messages.

System architecture

Response status hierarchy

Execution result status

Status	Description	Priority
`Success`	The execution was successful.	0
`PartialSuccess`	The execution was partially successful.	1
`Error`	The execution failed.	2

Error levels

Level	Description	Priority
`Info`	An informational message.	0
`Warn`	A warning message.	1
`Error`	An error message.	2

Retry policies

Policy	Description
`None`	Do not retry the operation.
`Once`	Retry the operation one time.
`Continuous`	The operation can be retried until it succeeds.

Error code categories

Error codes are categorized into three groups based on the processing stage:

Common: General errors related to request processing and UModel.
Phase1: Stage-one errors related to data sources, storage, and Prometheus Query Language (PromQL).
Phase2: Stage-two errors related to entity processing and method calls.

Common error codes

Basic request processing errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`InvalidRequestData`	400	None	Error	Request data format error	Check the request data structure and ensure all required fields are provided.
`ConvertFailed`	400	None	Error	Conversion failed: xxxx	Check the SPL syntax for compatibility with the target system.
`MissingParams`	400	None	Error	Missing required parameters: xxxx	Provide all required parameters as specified in the API documentation.
`InvalidParams`	400	None	Error	Invalid parameters: xxxx	Check the parameters against the API documentation to ensure they are valid.
`UnsupportedOperation`	400	None	Error	Unsupported operation: xxxx	Use a supported operation. Refer to the API documentation for details.

UModel-related errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`InvalidUModelData`	400	None	Error	Invalid UModel data	Check the UModel data format to ensure it is valid JSON.
`PartialInvalidUModelData`	200	None	Warn	Partial invalid UModel data, error: xxxx	Check the UModel data format to ensure it is valid JSON.
`UModelNotFound`	404	Continuous	Error	UModel data is empty, need to re-obtain	Reload the UModel configuration or check if the UModel service is available.
`ExpectedUModelNotFound`	400	Once	Error	UModel information not found: xxxx	Ensure the UModel configuration exists and is loaded correctly.

Validation and processing errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`ValidateFailed`	400	None	Error	Validation failed: xxxx	Check the data against the validation rules.
`ExtractParamsFailed`	400	Once	Error	Failed to extract parameters: xxxx	Ensure the parameter format is correct and accessible.
`InternalError`	500	None	Error	Internal error occurred in umode paas	Contact your system administrator.

Phase1 error codes

Data source-related errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`InvalidSourceType`	400	None	Error	Unsupported data source type	Use a supported data source type, such as `.metric_set`, `.log_set`, `.trace_set`, or `.event_set`.
`UnsupportedSourceType`	400	None	Error	Unsupported source type: xxxx	Use a supported source type, such as `labels` or `metrics`.
`UnsupportedQueryType`	400	None	Error	Unsupported query type: xxxx in MetricSet	Check the UModel documentation to ensure the query type is supported in MetricSet. Valid query types are `prom` and `spl`.
`UnsupportedDataSetType`	400	None	Error	Unsupported dataset type: xxxx	Use a supported dataset type, such as `metric_set`, `log_set`, `trace_set`, or `event_set`.

Storage-related errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`NotFoundStorageInfo`	400	Once	Error	Storage information not found	Ensure storage is configured and linked to the requested entity or dataset.
`InvalidStorageInfo`	400	None	Error	Invalid storage information	Check the UModel documentation and provide a complete storage configuration.
`MustUseSlsLogstore`	400	None	Error	xxxx requires SlsLogstore storage type	Configure Simple Log Service (SLS) LogStore as the storage type for this operation.
`MetricSetOnlySupportStorageType`	400	None	Error	xxxx only supports storage type: xxxx	Configure the correct storage type for the MetricSet operation.
`ListDataSetOnlySupportedStorageType`	400	None	Error	list_data_set only supports xxxx storage	Use a supported storage type for the `list_data_set` operation.

Dataset-related errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`DataSetUmodelNotFound`	400	Once	Error	DataSet UModel definition not found	Ensure the dataset is defined in the UModel configuration.
`TargetDataSetNotFound`	400	Once	Error	Target DataSet not found	Ensure the target dataset exists and is configured correctly.
`NotFoundMetricDefinition`	400	Once	Error	Metric definition not found: xxxx	Ensure the metric is defined in the UModel configuration.

PromQL-related errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`RewritePromQLFailed`	400	Once	Error	Failed to rewrite PromQL: xxxx, error: xxxx	Check the PromQL syntax for compatibility with the target system.
`StaticLabelQueryNotSupported`	400	None	Error	Static label query not supported	Use a dynamic label query.
`WhereExprToPromQLFailed`	400	Once	Error	Failed to convert Where expression to PromQL: xxxx, error: xxxx	Check the `where` expression syntax for compatibility with PromQL.

Expression-related errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`ExprParseFailed`	400	Once	Error	Failed to parse expression: xxxx, error: xxxx	Check the expression syntax. Refer to the UModel documentation for details.
`ExprExecFailed`	400	Once	Error	Failed to execute expression: xxxx, error: xxxx	Check that the expression format is correct. Refer to the UModel documentation for details.

Request errors of high-level APIs

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`InvalidUModelPaasRequestData`	400	None	Error	Invalid UModel Platform as a Service (PaaS) request data	Check the UModel PaaS request format and ensure all required fields are provided.
`InvalidUModelPaasRequestWhereExpr`	400	None	Error	Invalid Where expression	Check the `where` expression syntax to ensure it follows the correct format.
`InvalidUModelPaasRequestQuery`	400	None	Error	Invalid UModel PaaS request query data	Check that the query structure format is correct. Refer to the UModel documentation for details.

Phase2 error codes

Entity-related errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`EntitySetNotFound`	400	None	Error	EntitySet does not exist: xxxx@entity_set@xxxx	Ensure the EntitySet is defined in the UModel configuration.
`EntitySetUmodelNotFound`	400	None	Error	EntitySet[xxxx] UModel definition not found	Ensure the EntitySet is defined in the UModel configuration.
`EntityDataMismatch`	400	None	Error	Entity data rows do not match header	Ensure the entity data structure matches the defined header.
`DynamicEntityWithoutStorage`	400	None	Error	Dynamic Entity[xxxx] has no storage information	Configure storage information for the dynamic entity.
`InvalidEntityIds`	400	None	Error	Invalid entity IDs: xxxx	Provide valid entity IDs in the correct format.
`StorageQueryNotFound`	400	None	Error	Storage query not found	Ensure the storage query is configured correctly.

Method call-related errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`MissingFunctionCall`	400	None	Error	Phase 2 Object mode must contain function call	Add a function call to the SPL query. Example: `\| entity-call list_method()`
`InvalidEntitySetFunctionArguments`	400	None	Error	EntitySet function arguments error. xxxx	Check the function arguments to ensure they match the expected signature.
`MethodNotSupported`	400	None	Error	Method xxxx not supported	Use a supported method. Refer to the API documentation for details.
`DataSetUnSupportEntityCallFunction`	400	None	Error	xxxx unsupported method: xxxx	Use a supported method for this dataset type.

Related dataset errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`NoRelatedDataSetFound`	400	None	Error	No related xxxx found	Ensure the entity has related datasets.

Golden metric-related errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`NoGoldenMetricsFound`	400	None	Warn	No golden metrics found related to xxxx	Ensure the entity has golden metrics.
`TooManyGoldenMetrics`	200	None	Warn	Too many golden metrics found related to xxxx, now count is %d	Only the first eight golden metrics are returned. To improve performance, ensure the entity has fewer than eight golden metrics.

Neighbor entity query-related errors

Error code	HTTP status code	Retry policy	Level	Error message	Suggestion
`StorageLinkNotFound`	400	None	Error	Storage link [xxxx] not found	Ensure the StorageLink is configured correctly in UModel.
`UnsupportedStorageType`	400	None	Error	Unsupported storage type: xxxx	Use a supported storage type.
`UnsupportedRelationDirection`	400	None	Error	Unsupported direction: xxxx, only ‘in’ or ‘out’ supported	Use `in` or `out` as the relation direction.
`EntitySetLinkStorageMissing`	400	None	Error	Entity set link xxxx@entity_set@xxxx has no storage link configured	Configure a StorageLink for the EntitySet relationship.
`InvalidFieldMapping`	400	None	Error	Invalid field mapping: xxxx	Check the field mapping configuration to ensure the format is correct.

Best practices for error handling

1. Understand the error code

Each error includes the following information:

Code: A unique identifier for the error.
Level: The severity of the error (Info/Warn/Error).
Message: A description of the error.
Suggestion: A recommendation for resolving the error.
RetryPolicy: The recommended retry strategy.

2. Use the retry policy

Use the RetryPolicy to determine whether to retry a request:

None: Do not retry. Applies to non-recoverable errors such as syntax mistakes.
Once: Retry once. Applies to transient errors.
Continuous: Retry until the operation succeeds. Applies to recoverable issues such as resource constraints.

3. Handle common error scenarios

EntitySet does not exist

-- Error: The EntitySet does not exist.
.entity_set with(domain='apm', name='nonexistent.service')

-- Correct: Use an existing EntitySet.
.entity_set with(domain='apm', name='apm.service')

Missing function call

-- Error: The query is missing a required function call for Phase 2 mode.
.entity_set with(domain='apm', name='apm.service')

-- Correct: Add a function call.
.entity_set with(domain='apm', name='apm.service') 
| entity-call __list_method__()

Parameter validation failure

-- Error: Missing required parameter.
.metric_set with(name='apm.metric.apm.service')

-- Correct: Provide all required parameters.
.metric_set with(domain='apm', name='apm.metric.apm.service')

4. Use debugging techniques

Use inspection methods

-- Check available methods.
.entity_set with(domain='apm', name='apm.service') 
| entity-call __list_method__()

-- Check the configuration.
.entity_set with(domain='apm', name='apm.service') 
| entity-call __inspect__()

Use dry run mode

.set "umodel_paas_mode"='dry_run';
-- Execute the query to view the generated SPL.