alibabacloud-error-troubleshoot

Alibaba Cloud OpenAPI Troubleshoot

Guide users to diagnose Alibaba Cloud OpenAPI call failures using the OpenAPI Explorer troubleshoot APIs exposed as Aliyun CLI commands. These CLI commands call the same backend as the OpenAPI Diagnostic Portal.

Prerequisites

Install Aliyun CLI

Run aliyun version to verify version >= 3.4.0. If not installed or outdated, follow references/cli-installation-guide.md.

Install OpenAPI Explorer Plugin (MUST do this first)

This skill depends on the aliyun-cli-openapiexplorer plugin, which provides the three required CLI commands: openapiexplorer get-own-request-log, openapiexplorer get-request-log, openapiexplorer get-error-code-solutions.

Plugin name is `aliyun-cli-openapiexplorer` (NOT `openapiexplorer`). The install command uses --names:

aliyun configure set --auto-plugin-install true
aliyun plugin install --names aliyun-cli-openapiexplorer
aliyun plugin update

Verify it is available before running any troubleshoot command:

aliyun plugin list | grep openapiexplorer
aliyun openapiexplorer get-own-request-log --help

Command format rule (mandatory). Every troubleshoot command in this skill MUST use the exact kebab-case form under the openapiexplorer plugin:

• aliyun openapiexplorer get-own-request-log ...
• aliyun openapiexplorer get-request-log ...
• aliyun openapiexplorer get-error-code-solutions ...

PascalCase subcommands are strictly forbidden. Never invent or attempt any aliyun <product> <PascalCaseApi> style call as a substitute. If a troubleshoot command returns not a valid api, the openapiexplorer plugin is missing — re-run the install command above instead of switching to ActionTrail, web search, or re-issuing the original failing API. These three commands live only under the openapiexplorer plugin and have no equivalent in core product subcommands.

Check Alibaba Cloud Credentials

Run aliyun configure list to verify credentials are configured. If no valid profile is shown, STOP and ask the user to run aliyun configure outside this session.

Security rules:

• NEVER read, echo, or print AK/SK values
• NEVER ask the user to paste AK/SK into the conversation
• ONLY use aliyun configure list to check credential status
• Redact sensitive fields in log output (authenticationInfo.ak, tokens, etc.) when presenting results

Observability (MUST follow for every aliyun command)

Upon loading this skill, generate a random session ID once for the entire session:

• Format: 32-character lowercase hex string (e.g. a1b2c3d4e5f6789012345678901234ab)
• When: Generate once at session start; reuse the same value for every cloud API call in this session
• Placeholder: Use it as {session-id} in all commands below

Rule: Every `aliyun` CLI command that calls a cloud API MUST include the `--user-agent` flag.

Local utility commands (e.g. configure, plugin, version) do not support this flag and should be excluded.

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

Scenario Description

Use this skill when the user wants to:

• Look up request log details by Request ID (UUID from an API response or error)
• Understand why an API call failed (HTTP status, error code, caller identity, request parameters)
• Get official diagnostic solutions for a specific error code
• Troubleshoot permission / RAM / throttling / parameter issues on OpenAPI calls

RAM Permission Requirements

See references/ram-policies.md for minimum RAM policy JSON.

Permission failure handling: If a call returns Unauthorized or AccessDenied, stop and surface references/ram-policies.md. Do not retry with a different account without explicit user confirmation.

Core Diagnostic Workflow

Follow this decision tree. Full details: references/troubleshooting-workflow.md.

User has Request ID?
├── YES → Step 1: Query request log
│         ├── Default: get-own-request-log (current account only)
│         └── Request ID from sibling sub-account or main account: get-request-log
│         ├── Step 1 returns NotFound.RequestLog (404)?
│         │     └── TERMINATE: do NOT call get-error-code-solutions with `NotFound.RequestLog`.
│         │        Report log-unavailable cause (expired / wrong scope / no permission),
│         │        ask user for a fresh Request ID or the original error code, end the run.
│         ├── Step 2: Extract errorCode, errorMessage, product from logInfo.basicInfo
│         └── Step 3: If errorCode present → get-error-code-solutions
│            → Step 4: Summarize root cause + solutions + next steps
└── NO, only error code/message
    └── Step 3 directly: get-error-code-solutions (provide product if known)

⛔ Hard stop on log-NotFound: NotFound.RequestLog is the troubleshoot-API's own status for "no log available", not a business error code of the user's failed call. Feeding it to get-error-code-solutions will return irrelevant or empty results and is strictly forbidden. Always end the workflow at the NotFound branch and surface a user-facing recovery message instead.

Step 1: Query Request Log by Request ID

Request ID format: UUID, uppercase (e.g. BE7C768F-946F-5B46-80D4-F22FCFAF67C0).

Choose the right command:

Prefer `get-own-request-log` first — this mirrors the OpenAPI Diagnostic Portal behavior (GetOwnRequestLog is tried before GetRequestLog).

# Default: current account
aliyun openapiexplorer get-own-request-log \
  --log-request-id <REQUEST_ID> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

# Same parent account — main account or sibling sub-accounts
aliyun openapiexplorer get-request-log \
  --log-request-id <REQUEST_ID> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

Extract key fields from logInfo (use --cli-query to project):

aliyun openapiexplorer get-own-request-log \
  --log-request-id <REQUEST_ID> \
  --cli-query 'logInfo.basicInfo.{product:product,api:api,errorCode:errorCode,errorMessage:errorMessage,httpStatusCode:httpStatusCode,regionId:regionId,logRequestId:logRequestId}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

Step 2: Analyze the Log

Before fetching solutions, interpret the log:

1. `NotFound.RequestLog` (HTTP 404 from the lookup itself) — log is unavailable. STOP HERE. Do NOT proceed to Step 3. See "Hard stop on log-NotFound" above and "Troubleshooting CLI Errors → 6" below.
2. HTTP 200 + empty errorCode — call succeeded; user may be looking at the wrong Request ID or a downstream issue
3. HTTP 4xx/5xx or non-empty errorCode — proceed to Step 3
4. Throttling — check basicInfo.throttlingResult (e.g. FC.PASS vs throttle codes)
5. RAM / permission errors — look for AccessDenied, NoPermission, Forbidden.RAM in errorCode or response body; check callerInfo.callerType and whether STS role is involved
6. Parameter errors — cross-check logInfo.parameters against API documentation linked in basicInfo.apiDoc

Step 3: Get Error Code Solutions

Maps to troubleshoot-server sdkAgentService.getErrorCodeSolutions → OpenAPI GetErrorCodeSolutions.

⛔ Precondition — `errorCode` MUST come from `logInfo.basicInfo.errorCode` of a successfully retrieved log (or from the user's original error report). Never pass the lookup's own meta-status codes (NotFound.RequestLog, Unauthorized, AccessDenied produced by the get-*-request-log call itself) as --error-code. If Step 1 returned NotFound, the workflow has already terminated — do not enter Step 3.

aliyun openapiexplorer get-error-code-solutions \
  --error-code <ERROR_CODE> \
  --product <PRODUCT_CODE> \
  --error-message "<ERROR_MESSAGE>" \
  --accept-language zh-CN \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

Product code sources:

• logInfo.basicInfo.product from Step 1 (preferred)
• OpenAPI portal URL: https://api.aliyun.com/product/<ProductCode> → ProductCode is the segment after /product/

Present each solution's title/content clearly. An empty solutions array means no curated solution exists — fall back to log analysis and API documentation.

Step 4: Present Diagnosis

Always include:

1. What happened — API, product, region, HTTP status, error code/message
2. Who called — caller account type and ID (redact AK)
3. Root cause — from log analysis + solutions
4. Recommended actions — from solution content + any parameter/RAM fixes identified
5. CLI commands used — full copy-paste-ready commands (redact secrets)

Command Quick Reference

See references/api-reference.md for full parameter lists and examples.

Global Rules

• Always prefer `get-own-request-log` unless the Request ID belongs to the main account or another sub-account under the same parent account
• Request ID must be uppercase UUID — normalize before calling
• Always pass `--product` to get-error-code-solutions when available from the log
• Do not guess product codes — derive from log or OpenAPI portal URL
• Logs expire — if NotFound.RequestLog, the log may have expired (typically retained ~3 days) or the caller lacks permission
• Link to OpenAPI troubleshoot portal when helpful: https://api.aliyun.com/troubleshoot?q=<ErrorCode>&product=<Product>

Troubleshooting CLI Errors

Walk through in order when the user reports errors:

1. CLI version — aliyun version >= 3.4.0?
2. Plugin installed — aliyun plugin list | grep openapiexplorer?
3. Credentials — aliyun configure list shows valid profile?
4. Request ID format — uppercase UUID?
5. Wrong command for scope — 404 on get-own-request-log for main account or sibling sub-account Request ID? Retry with get-request-log (same parent account only). If still 404, the Request ID is from an unrelated account, expired, or invalid
6. NotFound.RequestLog (404) — log expired, wrong Request ID, or no permission. Message: "The log related to this logRequestId does not exist, has expired, or you do not have permission to view it."

• Hard rule: TERMINATE the diagnostic workflow here. Do NOT call get-error-code-solutions with --error-code NotFound.RequestLog (or any of the lookup's own meta-status codes like Unauthorized / AccessDenied produced by the get-*-request-log call). They are status codes of the troubleshoot API itself, not of the user's failing call — solution lookup will return irrelevant or empty results.
• Standard recovery message to the user: explain that the log is unavailable (expired ~3 days / Request ID is outside current account scope / lacks GetRequestLog permission), then ask for either (a) a fresh Request ID generated by a recent failing call from the current account, or (b) the original error code from the user's application logs — and end this turn.

1. Unauthorized / AccessDenied — see references/ram-policies.md
2. Empty solutions — no curated solution; analyze log fields and API docs instead

Full playbook: references/troubleshooting-workflow.md.

Reference Documents