DevOps Troubleshooting Matrix
Quick-fix diagnostic playbooks, error log signatures, root cause analyses, and verified solutions for production outages across the full DevOps toolchain.
AWS: is not authorized to perform
Fix "is not authorized to perform": run aws sts get-caller-identity, then simulate the action in IAM. Covers SCPs, boundaries, resource policies and AssumeRole.
502 Bad Gateway from an Application Load Balancer
Fix ALB 502 Bad Gateway: turn on access logs, then raise the target's keep-alive above the ALB idle timeout. Also covers health checks and security groups.
CannotPullContainerError: pull image manifest has been retried
Fix ECS CannotPullContainerError: add a NAT or VPC endpoints, grant the execution role ECR access, and check the image tag. Covers Fargate and secrets errors.
unable to place a task because no container instance met all of its requirements
Fix ECS "unable to place a task": read the closest-match reason, free the host port, add memory or CPU, or use a capacity provider. Covers ENI limits in awsvpc.
EKS nodes not joining the cluster
Fix EKS nodes not joining: attach the node IAM policies, open the API server path, check security groups and subnet tags, then read the instance bootstrap logs.
error: You must be logged in to the server (Unauthorized) on EKS
Fix EKS "You must be logged in to the server (Unauthorized)": run aws sts get-caller-identity, then add an access entry or aws-auth mapping. Covers lockouts.
The security token included in the request is expired
Fix ExpiredToken: run aws sts get-caller-identity, then refresh with aws sso login or assume the role again. Covers stale env vars, session length and CI OIDC.
not authorized to perform: iam:PassRole
Fix iam:PassRole denied: add iam:PassRole on the exact role ARN with an iam:PassedToService condition. Covers EC2 instance profiles and ECS task roles.
InsufficientInstanceCapacity: We currently do not have sufficient capacity
Fix InsufficientInstanceCapacity: retry in another availability zone, switch instance type, or accept a range of types. Covers Spot and Capacity Reservations.
Task timed out after N seconds
Fix Lambda "Task timed out": read the REPORT line, raise memory and timeout, and check VPC NAT access. Covers cold starts and in-function client timeouts.
An error occurred (AccessDenied) when calling the GetObject operation
Fix S3 AccessDenied on GetObject: run aws sts get-caller-identity, then the IAM policy simulator. Covers bucket policy, Block Public Access and ARN mistakes.
SignatureDoesNotMatch: The request signature we calculated does not match
Fix S3 SignatureDoesNotMatch: sync the system clock, strip whitespace from the secret key, and set the right region. Also covers proxies and presigned URLs.
ThrottlingException: Rate exceeded
Fix ThrottlingException "Rate exceeded": set AWS_RETRY_MODE=adaptive, cut API calls, and request a quota increase. Covers Terraform parallelism and DynamoDB.
Cannot connect to the Docker daemon
Fix "Cannot connect to the Docker daemon": run sudo systemctl start docker and sudo usermod -aG docker $USER. Covers contexts, Docker Desktop, WSL and CI.
Unable to download artifact: Artifact not found
Fix "Unable to download artifact: Artifact not found": match the upload and download names, order jobs with needs, and handle the v4 changes. Covers expiry.
Cannot connect to the Docker daemon in a CI job
Fix "Cannot connect to the Docker daemon" in CI: add a docker:dind service with DOCKER_HOST, bind the socket, or build with Kaniko or Buildah instead.
No space left on device on a CI runner
Fix "No space left on device" on a CI runner: remove unused toolchains, run docker system prune, and trim caches. Covers self-hosted runners and larger runners.
Not authorized to perform sts:AssumeRoleWithWebIdentity
Fix "Not authorized to perform sts:AssumeRoleWithWebIdentity": add id-token: write, print the OIDC claims, and match the trust policy sub and aud exactly.
GitHub Actions workflow not triggering
Fix a GitHub Actions workflow that will not trigger: validate the YAML, check branch and path filters and the default branch. Covers GITHUB_TOKEN and cron.
CrashLoopBackOff
Fix CrashLoopBackOff: run kubectl logs --previous and kubectl describe pod, then match the exit code to the cause. Covers OOMKilled, bad config and probes.
CreateContainerConfigError
Fix CreateContainerConfigError: run kubectl describe pod and read the Events. Usually a missing Secret, ConfigMap, key or ServiceAccount the Pod references.
Connection refused between Compose services on startup
Fix Compose "connection refused" at startup: add a healthcheck and depends_on with condition: service_healthy. Also covers migration gates and app retries.
Conflict. The container name is already in use by container
Fix "container name is already in use": run docker ps -a, then docker rm or docker rename the old container. Covers docker run --rm and Compose in CI.
docker-credential-desktop not installed or not available in PATH
Fix "docker-credential-desktop not installed": remove credsStore from ~/.docker/config.json or install a helper. Covers CI and the Kubernetes variant.
OCI runtime create failed: executable file not found in $PATH
Fix "executable file not found in $PATH": run docker run --rm -it --entrypoint sh image, then fix the COPY path, exec-form CMD or missing shell.
failed to solve: process "/bin/sh -c ..." did not complete successfully: exit code: 1
Fix "failed to solve: process did not complete successfully: exit code 1": rebuild with --progress=plain and debug the failing RUN layer interactively.
Docker: no space left on device
Fix Docker "no space left on device": run docker system df, then docker system prune and docker builder prune. Covers container logs, volumes and Desktop.
docker: port is already allocated
Fix "port is already allocated": run docker ps and lsof -i :PORT to find the owner, then stop it or change the host port. Covers Compose and localhost binds.
pull access denied, repository does not exist or may require authorization
Fix "pull access denied, repository does not exist": check the image name, then docker login to the right registry. Covers token scopes, Actions and Kubernetes.
exec format error
Fix "exec format error": check the image with docker inspect, then run docker buildx build --platform linux/amd64. Covers multi-arch images and CI.
fatal: Authentication failed for 'https://github.com/'
Fix Git "Authentication failed" on GitHub: use a personal access token instead of a password, clear the stale keychain entry, or switch the remote to SSH.
You are in 'detached HEAD' state
Fix detached HEAD: run git switch -c new-branch to keep your commits, or git switch main to leave. Covers recovering via reflog and why CI is detached.
error: Your local changes to the following files would be overwritten by merge
Fix "Your local changes would be overwritten by merge": run git stash, pull, then git stash pop. Or commit first, or discard with git restore. Pick by intent.
CONFLICT (content): Merge conflict in file
Fix a Git merge conflict: run git status, edit the conflict markers, git add the file, then git commit. Use git merge --abort to start over, or checkout --ours.
fatal: not a git repository (or any of the parent directories): .git
Fix "fatal: not a git repository" fast: check pwd, run git rev-parse --show-toplevel, then git init or re-clone. Covers safe.directory, submodules and Docker.
git: Permission denied (publickey)
Fix "Permission denied (publickey)": run ssh -vT git@github.com, ssh-add your key, chmod 600 it, and add the public key to your account. Covers multiple keys.
fatal: refusing to merge unrelated histories
Fix "refusing to merge unrelated histories": confirm with git log, then git pull --allow-unrelated-histories or rebase. Explains what the flag does.
git push rejected, non-fast-forward
Fix "rejected non-fast-forward": run git pull --rebase then git push. Use --force-with-lease only to overwrite on purpose, and recover lost commits via reflog.
error: src refspec main does not match any
Fix "src refspec main does not match any": make a first commit, or rename master with git branch -M main, then git push -u origin main. Covers typos and CI.
Error: Resource not accessible by integration
Fix "Resource not accessible by integration": add the missing scope to the permissions block, such as contents: write or pull-requests: write. Covers forks.
fatal: could not read Username for 'https://gitlab.com': No such device or address
Fix "could not read Username for gitlab.com" in CI: set git config insteadOf with CI_JOB_TOKEN, allow the job token, or use a deploy key over SSH.
This job is stuck because you don't have any active runners
Fix GitLab "job is stuck, no active runners": match job tags to the runner, allow protected branches, and check the runner is online. Covers shared runners.
Error: another operation (install/upgrade/rollback) is in progress
Fix Helm "another operation is in progress": run helm history, then helm rollback to the last good revision. Last resort: delete the pending release Secret.
Error: INSTALLATION FAILED: cannot re-use a name that is still in use
Fix Helm "cannot re-use a name": run helm list -A --all, then use helm upgrade --install, or helm uninstall the failed release. Covers other namespaces.
Error: nil pointer evaluating interface {} in a Helm template
Fix Helm "nil pointer evaluating interface {}": run helm template --debug, then add default, required or an if guard for the missing value. Add a values schema.
Error: rendered manifests contain a resource that already exists
Fix Helm "rendered manifests contain a resource that already exists": add Helm ownership labels and annotations to adopt it, or delete it. Covers CRDs.
Helm: UPGRADE FAILED and releases stuck pending
Fix Helm UPGRADE FAILED: run helm status and helm history, then helm rollback the pending release. Covers immutable fields, CRDs and using --atomic.
ImagePullBackOff and ErrImagePull
Fix ImagePullBackOff: run kubectl describe pod, then correct the image name or tag, add imagePullSecrets or fix registry access. Covers rate limits and TLS.
The connection to the server localhost:8080 was refused
Fix "connection to the server localhost:8080 was refused": check KUBECONFIG, then kubectl config get-contexts and use-context. Covers no kubeconfig and sudo.
context deadline exceeded
Fix Kubernetes "context deadline exceeded": find which component timed out, then check admission webhooks, API server and etcd, CSI calls, probes and kubectl.
Error from server (Forbidden): User cannot list resource
Fix "Forbidden: User cannot list resource": confirm with kubectl auth can-i, then add a Role and RoleBinding for the exact verb and apiGroup, not cluster-admin.
Init:CrashLoopBackOff
Fix Init:CrashLoopBackOff: run kubectl logs pod -c init-name, then check the dependency it waits on, migrations that cannot rerun, and volume permissions.
no matches for kind "X" in version "Y"
Fix "no matches for kind in version": run kubectl api-resources, then update the removed apiVersion or install the missing CRD first. Covers Helm and CI order.
Kubernetes node NotReady
Fix a NotReady node: run kubectl describe node, then check disk and memory pressure, the kubelet, container runtime and CNI. Includes journalctl commands.
Evicted: The node was low on resource: ephemeral-storage
Fix Pod eviction for ephemeral-storage: set requests and limits, cap emptyDir with sizeLimit, rotate container logs and tune image garbage collection.
Readiness probe failed: HTTP probe failed with statuscode: 503
Fix "Readiness probe failed: HTTP probe failed": curl the endpoint inside the Pod, correct the port and path, then raise initialDelaySeconds or timeoutSeconds.
Unable to attach or mount volumes: timed out waiting for the condition
Fix "Unable to attach or mount volumes": check Multi-Attach on a ReadWriteOnce volume, a zone mismatch or a stale attachment. Covers CSI drivers and limits.
bind: address already in use
Fix "bind: address already in use": run ss -ltnp or lsof -i :PORT to find the listener, then stop it. For TIME_WAIT, set SO_REUSEADDR. Covers IPv6 overlap.
fork: Cannot allocate memory
Fix "fork: Cannot allocate memory": run free -m, count threads, then check cgroup limits, ulimit -u and vm.overcommit_memory. Often not real memory exhaustion.
Could not get lock /var/lib/dpkg/lock-frontend
Fix "Could not get lock dpkg/lock-frontend": run ps aux | grep apt, wait for unattended-upgrades, then dpkg --configure -a. Do not delete the lock file.
No space left on device but df shows free space
Fix "No space left on device" with free space: run df -i for inodes and lsof +L1 for deleted open files. Covers wrong filesystems and finding the space with du.
Read-only file system
Fix "Read-only file system": run mount | grep ' ro', check dmesg for I/O errors, then mount -o remount,rw. Covers fsck, containers and cloud volumes.
sudo: unable to resolve host
Fix "sudo: unable to resolve host": add your hostname to /etc/hosts as 127.0.1.1 myserver, or set it with hostnamectl. Covers containers and cloud images.
Temporary failure in name resolution
Fix "Temporary failure in name resolution": check /etc/resolv.conf, test with dig @8.8.8.8, and restart systemd-resolved. Covers containers and search domains.
Too many open files
Fix "Too many open files": check the limit in /proc/PID/limits, find the leak with lsof, then raise LimitNOFILE in systemd. Covers Docker and Kubernetes.
OOMKilled (Exit Code 137)
Fix OOMKilled exit code 137: run kubectl describe pod to confirm, then raise the memory limit or fix the leak. Covers JVM and Node heap settings and sizing.
0/3 nodes are available: node(s) had untolerated taint
Fix "0/3 nodes are available: node(s) had untolerated taint": run kubectl describe node, then add a toleration or remove the taint. Covers control-plane nodes.
Pod stuck in Pending: 0/N nodes are available
Fix a Pod stuck in Pending: run kubectl describe pod and read FailedScheduling. Fix Insufficient cpu, taints, volume conflicts, PVC binding and node selectors.
PersistentVolumeClaim stuck in Pending
Fix a PVC stuck in Pending: run kubectl describe pvc, then add the CSI driver, set a valid StorageClass, fix zone or access mode. Covers WaitForFirstConsumer.
Service has no endpoints
Fix a Service with no endpoints: run kubectl get endpointslices, then match the selector to Pod labels and make the Pods Ready. Covers port mismatches.
Error: Backend configuration changed
Fix Terraform "Backend configuration changed": run terraform init -migrate-state to move state, or init -reconfigure to discard the old setup. Safe CI defaults.
Error: Cycle: resources depend on each other
Fix Terraform "Error: Cycle": run terraform graph to see it, then break the loop with separate security group rules, remove depends_on, or split modules.
Error: Inconsistent dependency lock file
Fix "Inconsistent dependency lock file": run terraform init, or terraform providers lock for every platform. In CI, use -lockfile=readonly instead of -upgrade.
Error: Invalid count argument
Fix "Invalid count argument": derive count from input variables, not resources created in the same run. Or switch to for_each, or apply with -target first.
Error: Invalid for_each argument
Fix "Invalid for_each argument": build the map keys from known inputs instead of values only known after apply. Covers data sources, modules and -target.
Error: Provider configuration not present
Fix "Provider configuration not present": restore the provider block and run terraform destroy, or use terraform state rm. Covers aliased providers in modules.
Error: resource already exists
Fix Terraform "resource already exists": run terraform import to adopt the object, or rename yours. Always plan after importing. Covers state drift.
Error: Saved plan is stale
Fix Terraform "Saved plan is stale": run terraform plan -out again, then apply that fresh plan. Use state locking so state cannot move between plan and apply.
Terraform. Error acquiring the state lock
Fix "Error acquiring the state lock": read the lock info, wait if a run is live, otherwise run terraform force-unlock LOCK_ID. Covers S3 and DynamoDB backends.
Error: Unsupported argument / An argument named X is not expected here
Fix Terraform "Unsupported argument": check the provider docs for your version, convert arguments to blocks, rename module inputs. Then run terraform validate.
toomanyrequests: You have reached your pull rate limit
Fix Docker Hub "toomanyrequests: You have reached your pull rate limit": run docker login, or pull via an ECR pull-through cache or a registry mirror.