---
title: "Troubleshooting Common OpenShift Issues"
canonical: "https://kb.uconn.edu/space/IKB/28728688684/Troubleshooting%20Common%20OpenShift%20Issues"
format: markdown
---
## Essential Diagnostic Commands

```shell
# Check pod status
oc get pods

# Get detailed pod info (events, conditions, resource usage)
oc describe pod <pod-name>

# View pod logs
oc logs <pod-name>

# View logs from a crashed/previous pod
oc logs <pod-name> --previous

# View recent events in your project
oc get events --sort-by='.lastTimestamp'
```

---

## Quick Reference: Pod Status Meanings

| Status | Meaning | First Step |
| --- | --- | --- |
| `Running` | Pod is healthy | All good |
| `Pending` | Waiting to be scheduled | `oc describe pod` — check Events |
| `CrashLoopBackOff` | Container keeps crashing | `oc logs --previous` |
| `ImagePullBackOff` | Can't pull the image | Check image name and registry credentials |
| `OOMKilled` | Out of memory | Increase memory limit |
| `Evicted` | Node pressure | Pods will reschedule; check resource usage |
| `Terminating` | Being deleted | Wait, or force: `oc delete pod <name> --force` |

---

## CrashLoopBackOff

**Symptom:** Pod keeps restarting. Status shows `CrashLoopBackOff`.

```shell
oc logs <pod-name>
oc logs <pod-name> --previous
oc describe pod <pod-name>
```

| Cause | Fix |
| --- | --- |
| Application error on startup | Check logs for stack traces. Fix the code or config |
| Missing environment variable | `oc set env deployment/my-app KEY=value` |
| Wrong port configured | Ensure your app listens on the port defined in the deployment |
| Failing health check | Adjust `initialDelaySeconds` or fix the health endpoint |
| Missing config file or secret | Verify ConfigMaps and Secrets are mounted correctly |

---

## ImagePullBackOff / ErrImagePull

**Symptom:** Pod stuck in `ImagePullBackOff` or `ErrImagePull`.

| Cause | Fix |
| --- | --- |
| Image name typo | Double-check the image URL and tag |
| Private registry, no credentials | Create a pull secret and link it to your service account |
| Image tag doesn't exist | Verify the tag exists in your registry |
| Registry unreachable | Check network/VPN connectivity to the registry |

---

## OOMKilled

**Symptom:** Pod is killed and restarted. Status shows `OOMKilled`.

**Fix:** Your application is exceeding its memory limit. Increase it:

```shell
oc set resources deployment/my-app --limits=memory=1Gi
```

> **Tip:** Monitor your application's actual memory usage with `oc adm top pods` to set appropriate limits.

---

## Build Failures

```shell
# View build logs
oc logs build/my-app-3

# List recent builds
oc get builds

# Check BuildConfig
oc describe buildconfig/my-app
```

| Cause | Fix |
| --- | --- |
| Dependency install fails | Check your requirements.txt, package.json, or pom.xml |
| Git repo not accessible | Verify the repo URL and access permissions / secrets |
| Dockerfile syntax error | Test your Dockerfile locally first with `podman build .` |
| Builder image issue | Try a different builder: `oc new-app python:3.11~https://...` |

---

## Application Not Accessible

```shell
# Check if the route exists
oc get routes

# Check if the service has endpoints
oc get endpoints

# Verify the service selector matches pod labels
oc describe service/my-app
oc get pods --show-labels
```

| Cause | Fix |
| --- | --- |
| No route created | `oc expose service/my-app` |
| Service selector doesn't match pod labels | Fix labels or recreate the service |
| App listening on wrong port | Ensure your app uses the port the service targets |

---

## Permission Issues

```shell
# Check what you can do in the current project
oc auth can-i --list

# Verify your current project
oc project
```

**Fix:** Ask your project admin to grant the appropriate role:

```shell
oc adm policy add-role-to-user edit [YOUR_NETID] -n [PROJECT_NAME]
```

---

## When to Contact ITS

Reach out to the ITS Platform Team if you encounter:

- Cluster-wide issues affecting multiple teams
- Node failures or unschedulable nodes
- Storage provisioning requests
- Quota increase requests
- Network policies blocking required traffic
- Certificate or SSO issues

---

*UConn ITS Infrastructure Services — OpenShift Knowledge Base*