How to fix default backend - 404 in Kubernetes

KubernetesBEGINNERMEDIUM

This error occurs when the Ingress controller cannot route traffic to a backend service. Fix it by verifying the service exists, checking label selectors match pods, ensuring correct path configuration, and adding rewrite annotations if needed.

What this error means

The "default backend - 404" error indicates that the Ingress controller received a request but couldn't find a matching rule to route it to a backend service. When no rules match, traffic goes to the default backend, which returns a 404 Not Found response. This typically happens when the hostname in the request doesn't match any Ingress rule, the path doesn't match, or the backend service doesn't exist or has no endpoints. The Ingress controller can only route traffic to services that exist and have healthy pods. The error can also occur when path-based routing is misconfigured—the Ingress forwards the original path to the backend, but the backend application expects a different path (usually root /).

How to fix "default backend - 404"

1Verify Ingress class and annotations

Check Ingress class is configured correctly:

bash

# List available ingress classes
kubectl get ingressclasses

# Describe ingress to see current configuration
kubectl describe ingress my-ingress -n default

Ensure Ingress has correct class:

yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    kubernetes.io/ingress.class: "nginx"  # For older versions
spec:
  ingressClassName: nginx  # For Kubernetes 1.18+

2Verify service exists and has endpoints

Check if the backend service exists and has healthy endpoints:

bash

# List services
kubectl get svc -n default

# Check endpoints (should show pod IPs)
kubectl get endpoints my-service -n default

# If endpoints are empty, check pod labels
kubectl get pods --show-labels
kubectl get svc my-service -o jsonpath='{.spec.selector}'

If endpoints show <none>, the service selector doesn't match any pod labels.

3Add rewrite-target for non-root paths

When using path-based routing, add rewrite annotation:

yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: api-service
            port:
              number: 8080

Without rewrite-target, backend receives /api/users when client requests /api/users. With rewrite-target: /, backend receives /users.

For capture groups:

yaml

annotations:
  nginx.ingress.kubernetes.io/use-regex: "true"
  nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - http:
      paths:
      - path: /api(/|$)(.*)
        pathType: ImplementationSpecific

4Verify host header matching

Test that hostname resolves and matches Ingress rule:

bash

# Get ingress IP
kubectl get ingress my-ingress

# Test with explicit host header
curl -H "Host: example.com" http://<ingress-ip>/

# Or test via hostname
curl http://example.com/

Ensure Ingress hosts match your request:

yaml

spec:
  rules:
  - host: example.com      # Must match Host header exactly
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

5Debug with ingress controller logs

Check ingress controller logs for routing errors:

bash

# Find ingress controller pod
kubectl get pods -n ingress-nginx

# Stream logs
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx -f

# Search for specific ingress
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller | grep "my-ingress"

Look for:
- "add rules for service" messages
- "successfully generated endpoint group"
- Any error messages about missing services

6Test service connectivity directly

Verify the service works independently of Ingress:

bash

# Port-forward to test service directly
kubectl port-forward svc/my-service 8080:80 -n default
# Then: curl http://localhost:8080/

# Or exec into a pod and test
kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \
  curl http://my-service.default.svc.cluster.local:80/

If service works directly but not through Ingress, the issue is in Ingress configuration.

How to fix default backend - 404 in Kubernetes

What this error means

Typical symptoms

Common causes

How to fix "default backend - 404"

Advanced notes

Related errors

Official resources & further reading