Troubleshooting EKS Cluster Access in Spacelift

Last updated: September 8, 2025

When deploying to EKS clusters through Spacelift, you may encounter errors like "failed to read resource state due to unreachable cluster" or "the server has asked for the client to provide credentials". This usually indicates that the IAM role Spacelift is using lacks proper access to the EKS cluster.

Resolution

Even if your IAM role has admin access to AWS resources, you need to explicitly grant it access to the EKS cluster through an access entry. Here's how to resolve this:

  1. Verify your AWS CLI configuration and profile setup in Spacelift hooks are correct

  2. Add an access entry in your EKS cluster configuration that specifies the IAM role Spacelift uses

Troubleshooting Steps

If you're experiencing cluster access issues, you can verify the problem with these steps:

  1. Test AWS credentials are working correctly: 

    aws sts get-caller-identity --profile your-profile-name

  2. Try accessing the cluster directly using kubectl: 

    aws eks update-kubeconfig --region your-region --name your-cluster-name
kubectl get pods --namespace your-namespace

If kubectl returns an error about providing credentials, this confirms you need to add an access entry for your IAM role in the EKS cluster configuration.

Common Error Messages

  • "failed to read resource state due to unreachable cluster" - indicates the Spacelift worker cannot access the EKS cluster

  • "the server has asked for the client to provide credentials" - indicates missing or incorrect access entries in EKS configuration

  • "Unexpected exit code when planning changes: 255" - may occur when the Spacelift worker cannot authenticate with the cluster