← Back to DevBytes
Developer Tutorial August 13, 2026 9 min read

Troubleshooting KrakenD API Gateway: Common Issues and Fixes

Introduction to KrakenD API Gateway Troubleshooting

KrakenD is a high-performance, open-source API Gateway that aggregates, transforms, and routes requests to multiple backend services. Built in Go, it is designed to handle massive throughput while providing features like rate limiting, authentication, circuit breaking, and response composition. However, like any distributed system component, KrakenD can encounter configuration errors, performance bottlenecks, and runtime issues that require systematic debugging.

This tutorial walks you through the most common KrakenD issues developers face, explains why they occur, and provides practical fixes with configuration examples. Whether you are running KrakenD in development or production, this guide will help you diagnose and resolve problems quickly.

Why Troubleshooting KrakenD Matters

An API Gateway sits at the critical intersection between clients and your backend services. When KrakenD malfunctions, the impact is immediate and widespread: every downstream consumer experiences failures. Common consequences of unresolved gateway issues include:

Mastering troubleshooting techniques ensures your gateway remains reliable, secure, and performant under real-world conditions.

Common Issues and Fixes

1. Configuration Validation Errors on Startup

The most frequent issue developers encounter is KrakenD refusing to start due to invalid configuration. KrakenD uses a strict JSON schema, and even minor syntax errors will prevent the service from booting. Always validate your configuration before deploying.

Symptom: KrakenD exits immediately with a schema validation error.

Fix: Use the built-in check command to validate your krakend.json file.

# Validate configuration before starting KrakenD
krakend check --config krakend.json --debug

# Expected output on success:
# Parsing configuration file: krakend.json
# The configuration is valid and ready to use

If validation fails, KrakenD will report the exact path of the offending field. A common mistake is forgetting the version field or using an incorrect endpoint structure:

{
  "version": 3,
  "name": "My Gateway",
  "port": 8080,
  "endpoints": [
    {
      "endpoint": "/users",
      "method": "GET",
      "backend": [
        {
          "url_pattern": "/api/users",
          "host": ["http://backend-service:3000"]
        }
      ]
    }
  ]
}

Ensure every endpoint has at least one backend with a valid host and url_pattern. Missing hosts or malformed URLs are the most common validation failures.

2. 404 Not Found for Defined Endpoints

Symptom: You defined an endpoint in the configuration, but KrakenD returns a 404 when you call it.

Common Causes and Fixes:

{
  "endpoint": "/users/{id}",
  "method": "GET",
  "backend": [
    {
      "host": ["http://user-service:3000"],
      "url_pattern": "/api/users/{id}"
    }
  ]
}

When using path parameters like {id}, ensure the same parameter name is used in both the endpoint and the backend url_pattern. Mismatched parameter names silently produce 404s or unexpected backend requests.

3. Backend Connection Timeouts

Symptom: Requests to KrakenD return 504 Gateway Timeout or take excessively long before failing.

KrakenD has multiple timeout layers. The timeout at the endpoint level controls how long KrakenD waits for all backends to respond. The backend-level timeout controls individual backend calls. If these values are too low, legitimate slow backends will be cut off.

{
  "endpoint": "/aggregate",
  "timeout": "3000ms",
  "backend": [
    {
      "host": ["http://slow-service:3000"],
      "url_pattern": "/data",
      "timeout": "2500ms"
    },
    {
      "host": ["http://fast-service:3000"],
      "url_pattern": "/info",
      "timeout": "1000ms"
    }
  ]
}

Best practice: The endpoint timeout should always be greater than or equal to the longest backend timeout. If the endpoint timeout is shorter, KrakenD will cancel in-flight backend requests prematurely. Also verify that your backend services are actually reachable:

# Test backend connectivity from the KrakenD container
curl -v http://slow-service:3000/data

# Check DNS resolution
nslookup slow-service

# Verify network policy allows traffic
kubectl get networkpolicy -n default

4. JWT Authentication Failures

Symptom: Valid JWT tokens are rejected with a 401 Unauthorized response.

KrakenD validates JWTs using the jwt-validator middleware. The most common causes of authentication failures are incorrect signing key configuration, wrong algorithm selection, or mismatched audience claims.

{
  "extra_config": {
    "github_com/devopsfaith/krakend-jose/validator": {
      "alg": "RS256",
      "jwk-url": "https://auth-service/.well-known/jwks.json",
      "cache": true,
      "disable_jwk_security": false,
      "audience": ["my-api"],
      "issuer": "https://auth-service"
    }
  }
}

Debugging steps:

You can decode a JWT locally to inspect its claims:

# Decode JWT header and payload (without verifying signature)
echo "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiYXVkIjoibXktYXBpIiwiaXNzIjoiaHR0cHM6Ly9hdXRoLXNlcnZpY2UifQ.signature" | cut -d. -f2 | base64 -d 2>/dev/null | jq .

5. Response Transformation and Data Mapping Issues

Symptom: The response from KrakenD is missing fields, has incorrect field names, or returns unexpected null values.

KrakenD's map_proxy and response manipulation features let you rename, filter, and restructure backend responses. Misconfigured mappings are a frequent source of data issues.

{
  "endpoint": "/profile",
  "backend": [
    {
      "host": ["http://user-service:3000"],
      "url_pattern": "/api/user",
      "mapping": {
        "first_name": "firstName",
        "last_name": "lastName",
        "email_address": "email"
      },
      "allow": ["firstName", "lastName", "email"]
    }
  ]
}

Key points:

6. Rate Limiting Misconfiguration

Symptom: Legitimate clients receive 429 Too Many Requests, or rate limiting has no effect at all.

KrakenD supports both endpoint-level and backend-level rate limiting. The token bucket algorithm is used, and misconfigured max_rate or capacity values cause unexpected behavior.

{
  "endpoint": "/api/search",
  "extra_config": {
    "github.com/devopsfaith/krakend-ratelimit/juju/router": {
      "maxRate": 100,
      "clientMaxRate": 10,
      "capacity": 50
    }
  },
  "backend": [
    {
      "host": ["http://search-service:3000"],
      "url_pattern": "/search",
      "extra_config": {
        "github.com/devopsfaith/krakend-ratelimit/juju/backend": {
          "maxRate": 200,
          "capacity": 100
        }
      }
    }
  ]
}

Understanding the parameters:

If rate limiting appears to have no effect, verify that the correct module path is used. KrakenD has multiple rate limiter implementations, and using the wrong module path silently disables the feature.

7. CORS Errors in Browser Clients

Symptom: Browser-based applications fail to call KrakenD endpoints with CORS errors in the console.

CORS must be explicitly configured in KrakenD. Missing or incorrect CORS configuration blocks all cross-origin browser requests.

{
  "extra_config": {
    "github_com/devopsfaith/krakend-cors": {
      "allow_origins": ["https://app.example.com"],
      "allow_methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
      "allow_headers": ["Authorization", "Content-Type", "X-Request-ID"],
      "expose_headers": ["X-Total-Count"],
      "allow_credentials": true,
      "max_age": "12h"
    }
  }
}

Common pitfalls:

8. Circuit Breaker Tripping Unexpectedly

Symptom: KrakenD returns 503 Service Unavailable even though backend services are healthy.

The circuit breaker opens when consecutive failures exceed a threshold. If the threshold is too low or the error threshold counts non-critical errors, the breaker trips prematurely.

{
  "backend": [
    {
      "host": ["http://backend-service:3000"],
      "url_pattern": "/api/data",
      "extra_config": {
        "github.com/devopsfaith/krakend-circuitbreaker/gobreaker": {
          "maxErrors": 5,
          "interval": "60s",
          "timeout": "10s",
          "maxConcurrentRequests": 50
        }
      }
    }
  ]
}

Tuning recommendations:

Debugging Tools and Techniques

Enabling Debug Logging

KrakenD's debug mode provides detailed request and response logging, which is invaluable for troubleshooting. Enable it at startup:

# Run KrakenD with debug logging
krakend run --config krakend.json --debug

# Or set the log level via environment variable
export KRAKEND_LOG_LEVEL=DEBUG
krakend run --config krakend.json

Debug mode logs every backend call, response status, and transformation step. Use it in development but never in production due to the high log volume.

Using the Metrics Endpoint

KrakenD exposes Prometheus metrics that reveal runtime behavior. Enable the metrics endpoint in your configuration:

{
  "extra_config": {
    "github_com/devopsfaith/krakend-metrics": {
      "collection_time": "60s",
      "proxy_disabled": false,
      "router_disabled": false,
      "backend_disabled": false,
      "endpoint_disabled": false,
      "listen_address": ":8090"
    }
  }
}

Access metrics at http://localhost:8090/__metrics and scrape them with Prometheus. Key metrics to monitor include:

Inspecting Backend Responses

When KrakenD returns unexpected data, bypass the gateway and call backends directly to isolate the issue:

# Call the backend directly
curl -s http://backend-service:3000/api/users | jq .

# Call through KrakenD
curl -s http://localhost:8080/users | jq .

# Compare the two responses to identify transformation issues
diff <(curl -s http://backend-service:3000/api/users | jq .) \
     <(curl -s http://localhost:8080/users | jq .)

Best Practices for KrakenD Reliability

1. Always Validate Configuration in CI

Integrate the krakend check command into your CI/CD pipeline to catch configuration errors before deployment:

# GitHub Actions example
- name: Validate KrakenD config
  run: |
    docker run --rm -v $(pwd)/krakend:/etc/krakend \
      devopsfaith/krakend:2.5.0 \
      krakend check --config /etc/krakend/krakend.json --debug

2. Use Environment Variables for Sensitive Configuration

Never hardcode secrets in your KrakenD configuration. Use the env parser to inject values at runtime:

{
  "extra_config": {
    "github_com/devopsfaith/krakend-jose/validator": {
      "alg": "RS256",
      "jwk-url": "{{JWK_URL}}",
      "cache": true
    }
  }
}

Then set the environment variable when starting KrakenD:

export JWK_URL=https://auth-service/.well-known/jwks.json
krakend run --config krakend.json

3. Implement Health Checks

Configure health check endpoints so orchestrators like Kubernetes can manage KrakenD pods properly:

{
  "endpoints": [
    {
      "endpoint": "/__health",
      "method": "GET",
      "backend": [
        {
          "host": ["http://backend-service:3000"],
          "url_pattern": "/health",
          "timeout": "2000ms"
        }
      ]
    }
  ]
}

4. Set Appropriate Timeouts at Every Layer

Timeouts should cascade logically from the client through KrakenD to the backend. A good rule of thumb is:

5. Monitor and Alert Proactively

Set up alerts on key KrakenD metrics to catch issues before users notice them:

# Prometheus alerting rule example
- alert: KrakenDHighErrorRate
  expr: |
    sum(rate(krakend_proxy_request_total{status=~"5.."}[5m])) /
    sum(rate(krakend_proxy_request_total[5m])) > 0.05
  for: 5m
  labels:
    severity: critical
  annotations:
    summary: "KrakenD error rate above 5%"
    description: "KrakenD is returning 5xx errors for more than 5% of requests."

Conclusion

Troubleshooting KrakenD effectively requires understanding its layered architecture, from endpoint configuration through backend communication to response transformation. By following the systematic approaches outlined in this tutorial — validating configurations, enabling debug logging, monitoring metrics, and isolating issues by testing backends directly — you can quickly identify and resolve the most common KrakenD problems. Remember that prevention is always better than cure: integrate configuration validation into your CI pipeline, use environment variables for secrets, set appropriate timeouts at every layer, and implement proactive monitoring. With these practices in place, your KrakenD deployment will remain a reliable, high-performance gateway that seamlessly connects your clients to your backend services.

— Ad —

Google AdSense will appear here after approval

← Back to all articles