# ecs-image-troubleshooting

Part of **ECS**

# ECS Image Management Troubleshooting Guide

## Problem Index

| Problem | Symptom | Severity | Solution Summary |
|--------|---------|----------|------------------|
| Invalid Marketplace Image Reference | Error: `InvalidParameter.ProductCode` | High | Verify the image has a valid ProductCode and is from the marketplace |
| Cannot Delete Image in Use | Error: `ResourceInUse` | Medium | Disassociate the image from instances or use force-delete option |
| Permission Denied During Image Operation | Error: `Forbidden` | High | Grant required RAM permissions or OSS access to the user/role |
| FTP Connection Fails with Error 425 | Error: `425 Can't open data connection` | Medium | Configure and open passive mode port range in firewall and vsftpd |
| Image Import Fails Due to Missing File | Error: `NoSuchObject` | High | Confirm OSS URL is correct and file exists in the specified bucket |

## Problem Details

### Problem 1: Invalid Marketplace Image Reference

**Symptoms**
- Error message: `InvalidParameter.ProductCode`
- Behavior: API call to create an instance or describe an image fails when referencing a marketplace image
- Context: Occurs when using an image ID that appears to be from the marketplace but lacks a valid `ProductCode`, or when the `ProductCode` is malformed

**Root Cause**
- The `ProductCode` field identifies an image as originating from the cloud marketplace. If this field is missing, empty, or invalid in the request, the system rejects it because marketplace licensing and billing depend on this identifier.
- Common when copying a marketplace image without preserving metadata, or manually entering an incorrect image ID.

**Solution**
1. Use the `DescribeImages` API to verify the image’s `ProductCode`:
   ```bash
   aliyun ecs DescribeImages --ImageId m-1234567890abcdef0 --RegionId cn-hangzhou
   ```
2. In the response, confirm that `Images[].ProductCode` is a non-empty string (e.g., `"abcd000111"`).
3. If creating an instance via API, include the correct `ImageId` and ensure the region matches the one where the marketplace image is available.
4. In the console, obtain the image ID directly from the [Cloud Marketplace](https://market.aliyun.com) product page for your target region.

**Verification**
- Re-run the `DescribeImages` call and confirm `ProductCode` is present.
- Attempt to launch an instance using the verified image ID—operation should succeed without `InvalidParameter.ProductCode`.

### Problem 2: Cannot Delete Image in Use

**Symptoms**
- Error message: `ResourceInUse`
- Behavior: Delete operation fails even though no active instances appear to be using the image
- Context: Occurs during deletion of custom or shared images that are still referenced by instances, launch templates, or shared accounts

**Root Cause**
- ECS prevents deletion of images that are actively used to avoid breaking dependent resources. This includes:
  - Running or stopped instances created from the image
  - Launch templates referencing the image
  - Shared images accepted by other accounts (even if unused)

**Solution**
1. Check for instances using the image:
   ```bash
   aliyun ecs DescribeInstances --ImageId m-1234567890abcdef0 --RegionId cn-hangzhou
   ```
2. Terminate or replace the system disk of any dependent instances.
3. Check launch templates:
   ```bash
   aliyun ecs DescribeLaunchTemplates --RegionId cn-hangzhou
   ```
   Update or delete templates referencing the image.
4. If the image was shared, unshare it first:
   ```bash
   aliyun ecs ModifyImageSharePermission --ImageId m-1234567890abcdef0 --RemoveAccount.1 123456789012 --RegionId cn-hangzhou
   ```
5. Retry deletion. If urgent and dependencies are acceptable to break, use **force delete** in the console (not available via API).

**Verification**
- After cleanup, the `DeleteImage` call should succeed:
  ```bash
  aliyun ecs DeleteImage --ImageId m-1234567890abcdef0 --RegionId cn-hangzhou
  ```
- Confirm the image no longer appears in `DescribeImages` output.

### Problem 3: Permission Denied During Image Operation

**Symptoms**
- Error message: `Forbidden`
- Behavior: Operations like copying, importing, or exporting images fail despite correct parameters
- Context: Common when using RAM users, roles, or cross-account scenarios without sufficient permissions

**Root Cause**
- The calling identity lacks required permissions for:
  - Accessing source/target regions (for copy)
  - Reading/writing to OSS buckets (for import/export)
  - Using KMS keys (for encrypted images)
  - Modifying image attributes (for sharing/deletion)

**Solution**
1. For OSS-based operations (import/export), ensure the RAM user/role has:
   - `oss:GetObject`, `oss:PutObject` on the bucket
   - `ecs:ImportImage` or `ecs:ExportImage` permission
2. Attach a policy like:
   ```json
   {
     "Version": "1",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["ecs:ImportImage", "ecs:ExportImage"],
         "Resource": "*"
       },
       {
         "Effect": "Allow",
         "Action": ["oss:GetObject", "oss:PutObject"],
         "Resource": "acs:oss:*:*:your-bucket/*"
       }
     ]
   }
   ```
3. For encrypted images, grant `kms:Decrypt` and `kms:GenerateDataKey` on the KMS key.
4. Use the console path: **RAM Console > Policies > Create Policy**, then attach to the user/role.

**Verification**
- Re-run the failed operation—it should now complete without `Forbidden`.
- Use the **Policy Simulator** in RAM console to validate permissions beforehand.

### Problem 4: FTP Connection Fails with Error 425

**Symptoms**
- Error message: `425 Can't open data connection`
- Behavior: FTP client connects but fails during file listing or transfer
- Context: Occurs when using passive (PASV) mode on ECS instances behind security groups or firewalls

**Root Cause**
- In passive mode, the FTP server opens a random high-numbered port for data transfer. If this port range is not allowed in the ECS security group or OS firewall (`iptables`/`firewalld`), the connection fails.

**Solution**
1. Edit `/etc/vsftpd/vsftpd.conf` to define a fixed passive port range:
   ```bash
   sudo vim /etc/vsftpd/vsftpd.conf
   ```
   Add:
```text
   pasv_enable=YES
   pasv_min_port=50000
   pasv_max_port=50100
   ```
2. Restart vsftpd:
   ```bash
   sudo systemctl restart vsftpd
   ```
3. In the ECS console, add inbound rules to the instance’s security group:
   - Protocol: TCP
   - Port range: `50000/50100`
   - Source: `0.0.0.0/0` (or restrict to client IPs)
4. If using OS firewall, allow the range:
   ```bash
   sudo firewall-cmd --permanent --add-port=50000-50100/tcp
   sudo firewall-cmd --reload
   ```

**Verification**
- Connect via FileZilla or similar client in passive mode.
- Successful directory listing and file transfer confirm the fix.

### Problem 5: Image Import Fails Due to Missing File

**Symptoms**
- Error message: `NoSuchObject`
- Behavior: `ImportImage` task fails immediately or after initial validation
- Context: When importing from an OSS URL that points to a non-existent or inaccessible object

**Root Cause**
- The OSS object URL provided in the `DiskDeviceMapping` does not exist, has been deleted, or the bucket/object name contains typos. The ECS service cannot locate the VHD/RAW/QCOW2 file.

**Solution**
1. Verify the OSS object exists using the OSS console or CLI:
   ```bash
   aliyun oss ls oss://your-bucket/path/to/image.vhd
   ```
2. Ensure the URL format in the API request uses the **internal endpoint** if the ECS and OSS are in the same region:
```text
   https://your-bucket.oss-cn-hangzhou-internal.aliyuncs.com/image.vhd
   ```
3. Confirm the RAM role attached to the ECS service (or your user) has `oss:GetObject` on the object.
4. Re-submit the import request with the corrected URL.

**Verification**
- Monitor the import task in the ECS console under **Tasks**.
- Status changes from “Processing” to “Success” indicates successful import.

## FAQ

**Q: How do I check if an image is from the cloud marketplace?**  
A: Call `DescribeImages` with the image ID and check if the `ProductCode` field in the response is a non-empty string. Only marketplace images have a valid `ProductCode`.

**Q: What permissions are required to share an encrypted custom image across accounts?**  
A: The image owner must grant the recipient account permission to use the image via `ModifyImageSharePermission`. Additionally, if the image is KMS-encrypted, the recipient must have access to the same KMS key or the key must be shared with them.

**Q: Why does my custom image creation fail even though the instance is running?**  
A: Custom images can only be created from instances with a **system disk snapshot**. Ensure you’re creating the image from the instance (not a data disk), and that the instance is in the “Running” or “Stopped” state—not “Starting” or “Stopping”.

**Q: How can I view the progress of an image import task?**  
A: In the ECS console, go to **Tasks** (accessible via top navigation bar) or check the **Custom Images** list in the target region—the image will show “Creating” status until complete.

**Q: Are there limits on the number of custom images I can create?**  
A: Yes, each Alibaba Cloud account can create up to 100 custom images by default. You can request a quota increase via the Quota Center if needed.