/alibabacloud-error-troubleshoot

name: alibabacloud-error-troubleshoot
description: |
  Alibaba Cloud OpenAPI troubleshooting skill. Use this skill when the user needs to diagnose API call failures
  using Request ID, error codes, or error messages — via Aliyun CLI `openapiexplorer` plugin commands.
  Triggers: "RequestId 排查", "Request ID 诊断", "错误码解决方案", "API 调用失败", "get-request-log",
  "get-own-request-log", "get-error-code-solutions", "OpenAPI 故障排查", "API troubleshoot",
  "diagnose OpenAPI", "diagnose OpenAPI error codes", "diagnose OpenAPI error messages",
  "Diagnose OpenAPI API call failures using Request ID".

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](https://api.aliyun.com/troubleshoot).

---

Prerequisites

Install Aliyun CLI

Run `aliyun version` to verify version **>= 3.4.0**. If not installed or outdated, follow [references/cli-installation-guide.md](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

| API | CLI Command | Purpose | |-----|-------------|---------| | GetOwnRequestLog | `get-own-request-log` | Query logs for API calls made by the **current account** | | GetRequestLog | `get-request-log` | Query logs for Request IDs under the **same parent account** — main account and all its sub-accounts | | GetErrorCodeSolutions | `get-error-code-solutions` | Fetch diagnostic solutions for an error code |

See [references/ram-policies.md](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](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](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