FAQ and troubleshooting

Can one migration task migrate multiple environments?

No. A migration task is associated with only one environment of one source instance and one destination gateway. To migrate multiple environments, such as Production, Pre-release, and Test, prepare separate destination gateways and create separate migration tasks.

Which source instance types can be migrated?

The migration tool supports dedicated and Serverless source instances. Cluster instances are not supported.

If you select a Serverless instance, all Serverless API groups in the current region for the current Alibaba Cloud account are included in the assessment. For each group, only configurations in the environment selected for the task are migrated. Custom domain names, certificates, Apps, authorization relationships, API groups, and APIs are migrated based on the corresponding rules. A Serverless instance does not have an independent network ingress. Therefore, instance-level IP access control configurations are not migrated. Before you migrate API group configurations, make sure that the destination gateway can access the backend services of all API groups.

Does creating a migration task affect services on the source gateway?

No. Creating a task and running an assessment only read source configurations. They do not modify source resources or switch traffic.

Why is a resource marked as Partially Supported?

The resource can be migrated, but some configurations are not automatically converted, or their behavior after migration differs from that in Traditional API Gateway. Review the migration instructions and destination configuration preview, and add items that require manual handling to your release and verification checklist.

The migration support status of an API does not include plug-in compatibility. Even if an API is marked as Supported, separately inspect its plug-ins based on Differences in plug-in capabilities.

What do I do if a source configuration changes?

Reassess the task and make sure that the resource list and destination configuration preview are updated before you continue the migration. We recommend that you freeze or minimize source configuration changes during migration.

Can I migrate only a subset of resources?

Yes. In each migration stage, you can search by resource name or resource ID and select resources to migrate. We still recommend that you migrate instance configurations, domain name configurations, App configurations, and API group configurations in that order to satisfy resource dependencies.

Search only filters the resources displayed on the page. Clicking Execute all still migrates all migratable resources in the current stage. To migrate only the search results, select the required resources and click Execute.

Do I need to migrate all resources again after a failure?

Usually, no. If you fix permissions, network connectivity, or resource dependencies on the destination gateway, retry the failed resources. If you modify a Traditional API Gateway configuration, reassess the task before you return to the execution page and rerun the resource. Successful resources are not migrated again by default.

Which API type do I select when I migrate API group configurations?

REST API is selected by default. Standard paths and explicit request methods can be migrated to a REST API. If a source API uses the ANY request method or uses /* to match all subpaths and you need to retain the corresponding behavior, select HTTP API. If you select REST API, these source APIs are skipped.

Select the same API type when you review the destination configuration preview and run the migration. The option applies only to the current execution. When you rerun the migration for the same group, use the same API type.

What do I do if a resource with the same name already exists on the destination gateway?

For an IP access control policy, domain name, or Consumer with the same name, the destination resource is reused by default and its existing configuration is not modified. To update the destination resource with the migrated configuration, select Allow updates when a target resource with the same name is encountered. An existing certificate with the same name is only reused and is never overwritten by the migration tool.

For an API with the same name and the same type, the existing API is not modified by default and the resource is marked as Skipped. To update it, select Allow updates when a target API with the same name is encountered. Before you enable the option, review the target configuration preview and the existing destination configuration.

If the destination API with the same name has a different type from the one selected for the current migration, the migration tool cannot reuse or update it across API types, and the API group migration fails. Handle the destination API with the same name, or select another destination gateway and retry.

How is a Function Compute 2.0 backend migrated?

• A Function Compute 2.0 HTTP function is converted into a DNS Service by using the original HTTP trigger URL and complete invocation Path. After migration, verify network connectivity from the destination gateway to the address and test the actual invocation result.

• A Function Compute 2.0 Event function cannot be migrated. A source API that uses this backend is not migrated. To migrate the API, first change the backend to a supported type and reassess the task.

Why is integrity Inconsistent when the resource migration is Successful?

The migration state indicates whether the resource migration operation is complete. Integrity indicates whether the number of actual matched configurations on the destination gateway meets the expectation for this migration. The two results are independent. After a successful migration, integrity can be Inconsistent if configurations such as domain name bindings, credentials, backend services, plug-ins, policies, Operations, or Routes are missing on the destination gateway.

Click View next to the integrity result to compare the expected count and actual matched count of each check item. After you resolve differences on the destination gateway, click Check again to refresh the result. To write the migrated configuration again, rerun the corresponding resource.

Why should I migrate API group configurations last?

API group configurations reference destination domain names and Consumers. Migrating domain names and Apps first prevents missing domain name bindings or caller authorizations after APIs are imported.

Does clicking Complete Migration automatically switch traffic?

No. Complete Migration only marks the configuration migration stage as complete. You must still publish the destination APIs, verify them through direct requests, and switch business traffic by adjusting DNS weights.

Does canceling or deleting a task roll back destination resources?

No. Canceling or deleting a task does not delete resources migrated to the destination gateway and does not restore reused resources or an updated API with the same name to its original configuration. Record execution results before you decide whether to manually delete destination resources.

Why is a destination API inaccessible after a successful migration?

Check the following items in order:

1. Whether the API is published.

2. Whether the custom domain name is associated with the corresponding API or Route and its certificate is valid.

3. Whether Consumer credentials and the authorization to call the Operation or Route are correct.

4. Whether the destination gateway can connect to the backend service.

5. Whether IP access control, throttling, authentication, or another plug-in rejects the request.

6. Whether the request Host header, path, method, and parameters match the destination API definition.

How do I verify the destination gateway without changing DNS records?

If the destination gateway ingress is an IP address, use the hosts file, a test DNS service, or curl --resolve. If the ingress is a domain name, use curl --connect-to. Continue to use the business domain name for HTTPS requests so that the correct Host header and TLS SNI are sent. For commands, see Verify APIs and switch traffic by using DNS.

What do I do if signature authentication fails?

Check the Consumer credential, signature algorithm, request timestamp, headers and query parameters included in the signature, and special-character encoding. We recommend that you run regression tests with an actual client or an official SDK instead of relying only on a simple health check.

What do I do if a backend response differs from Traditional API Gateway?

Check parameter mappings, constant parameters, Request/Response Transformation, Backend Signature, Error Mapping, and the final result after multiple plug-ins take effect. Compare the destination configuration preview with Differences in plug-in capabilities, adjust configurations, and test again.

Why does the actual request percentage differ from the DNS weight?

DNS weights usually apply to DNS queries or clients rather than each HTTP request. Recursive DNS servers, client caches, persistent connections, and the scheduling algorithm of the DNS service can cause the actual traffic percentage to differ.

How long should I wait before proceeding to the next stage after a DNS adjustment?

We recommend that you observe the system for at least two TTL periods and for the minimum observation period defined for your service. If multiple DNS record types are involved, use the longest TTL. Increase the destination gateway weight only if no rollback condition is triggered and data consistency checks pass.

What do I need to consider for IPv4 and IPv6 dual-stack access?

If separate A and AAAA records are configured, include both record types in the same traffic switch plan, use the same destination traffic percentage at each stage, and separately verify IPv4 and IPv6 request volume and business metrics. Restore both record types during a rollback.

How do I quickly roll back traffic?

Restore the weights of all DNS records that point to Traditional API Gateway and are involved in the traffic switch to 100%, change all destination gateway record weights to 0%, and observe cache expiration and traffic returning to the source gateway. DNS and client caches can delay a rollback. Retain the configurations and capacity of Traditional API Gateway throughout the traffic switch.

Do I need to restore the TTL after all traffic is switched?

Yes. After full traffic remains stable for the predefined observation period, restore the TTL that you temporarily reduced before migration to its normal operating value.

When can I decommission Traditional API Gateway?

Decommission the source Traditional API Gateway instance in accordance with your decommissioning process only after all DNS records involved in the traffic switch point to the destination gateway and sufficient observation confirms that no residual traffic, fixed-IP calls, other domain-name-based access endpoints, or external service dependencies remain. Do not release source resources immediately after a DNS adjustment.