All Products
Search

This Product

    Container Service for Kubernetes:Troubleshoot edge node issues

    Document Center

    Container Service for Kubernetes:Troubleshoot edge node issues

    Last Updated:Mar 26, 2026

    Use this page to troubleshoot common connection and upgrade failures for edge nodes in ACK Edge clusters. Search this page for a fragment of the error message you see — each entry maps the error to its cause and fix.

    If your issue is not listed, collect diagnostic information from the node and submit a ticket. For instructions, see Collect node diagnostic information.

    Handle edge node connection failures

    Run the node connection script to connect an edge node to the cluster. If the script fails, match your error message in the table below.

    Error message Cause Fix
    The os XXX unsupport The operating system version is not supported. See Add an edge node for supported operating system versions.
    Invalid nodeName The node name does not meet naming rules. Use a name that: contains only lowercase letters, hyphens (-), and periods (.); is 1–253 characters long; does not start with localhost.
    Node route overlaps with service cidr The node route conflicts with the pod CIDR block or Service CIDR block. Recreate the cluster and reconfigure the pod CIDR block and Service CIDR block so they do not overlap with the NameServer address or node route.
    response error msg: TOKEN_EXPIRED The connection token has expired. Generate a new node connection script. Also check that the node's system clock is accurate.
    A node named XXX is already exist in the cluster A node with this name already exists in the cluster. Remove the existing node with the same name from the cluster, then run the connection script again.
    error run phase join-node: failed to get cluster info: failed to get cluster-info configmap, Get "https://xx.xxx.xx.xx:6443/api/v1/namespaces/kube-public/configmaps/cluster-info": dial tcp xx.xxx.xx.xx:6443: i/o timeout edgeadm could not reach the API server. edgeadm connects to the API server by IP address. Check whether the access control list (ACL) rules on the Server Load Balancer (SLB) instance fronting the API server block the node's IP address.
    error run phase join-node: Install edge-hub failed: Copy file /tmp/edge-hub to /usr/bin/edge-hub fail: open /usr/bin/edge-hub: text file busy | 40009 | 40009 An edge-hub binary already exists on the node. Run edgeadm reset to clear the node, then run the connection script again.
    error run phase post-check: timed out waiting for the condition System components failed to start. 1. Download the latest edgeadm, run edgeadm reset, and run the connection script again. 2. Confirm the node can reach all required public endpoints — see Configure endpoints and IP routing for edge nodes. 3. If the issue persists, collect diagnostic information and submit a ticket.

    Handle edge node upgrade failures

    When you update an edge node pool, the upgrade is complete when the node returns This node has been upgraded successfully. If that message does not appear, match your error in the table below.

    Error message Cause Fix
    edgeadm version xxxx does not match cluster version The edgeadm version does not match the cluster version. 1. Verify the cluster control plane has been upgraded. 2. Check that TARGET_CLUSTER_VERSION is set to the correct value.
    node has already been upgraded to xxx The node is already at the target version. If specific components on the node were not upgraded, retain the logs and submit a ticket.
    kubelet target version xxxx does not match cluster version xxxx The kubelet version does not match the control plane version. If you specified kubelet-version, verify its value matches the control plane version. If the parameter was left blank, submit a ticket.
    Parameter currentVersion cann't null An older version of edgeadm is in use. Download the latest edgeadm. Note that valid upgrade paths are Kubernetes 1.18 → 1.20 and Kubernetes 1.20 → 1.22.

    upgrade kubelet failed at phase install, recover to previous state.

    error run phase upgrade: xxxx

    		 The upgrade failed and was automatically rolled back. The node status is not affected. Retain the logs and submit a ticket.

    upgrade kubelet failed at phase install, recover to previous state

    recover kubelet failed, err: xxx

    error run phase upgrade: xxxx

    		 The upgrade failed and rollback also failed. The node status is affected. Retain the logs and submit a ticket.

    Collect node diagnostic information

    When an edge node in an ACK Edge cluster behaves abnormally, run the diagnostic script to collect information for analysis.

    1. Log on to the abnormal edge node.

    2. Download the diagnostic script.

      curl -o /usr/local/bin/diagnose_edge_node.sh https://aliacs-k8s-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/public/diagnose/diagnose_k8s.sh

    3. Make the script executable.

      chmod u+x /usr/local/bin/diagnose_edge_node.sh

    4. Switch to the directory.

      cd /usr/local/bin/

    5. Run the diagnostic script.

      ./diagnose_edge_node.sh

      Each run generates a uniquely named archive. The output looks similar to:

      + echo 'please get diagnose_1578310147.tar.gz for diagnostics'
please get diagnose_1578310147.tar.gz for diagnostics
+ echo 'Submit the file named diagnose_1578310147.tar.gz to request technical support.'
Submit the file named diagnose_1578310147.tar.gz to request technical support.

    6. Verify the archive was created.

      ll

    Attach the generated .tar.gz file when you submit a ticket.