503 Service Unavailable when completing usertask

Camunda 8 Topics
2

Hi there! :wave:

I can help you troubleshoot this 503 Service Unavailable error when completing user tasks in Camunda 8 Self-Managed. This is a known issue with several potential causes. Let me walk you through the most common solutions:

:mag: Most Common Causes & Solutions:

1. Check Your API Endpoint

Make sure you’re using the correct REST API endpoint:

  • :white_check_mark: Correct: /v1/tasks/{taskId}/complete (Tasklist API, typically port 8082)
  • :x: Avoid: /v1/user-tasks/{userTaskKey}/completion or /v2/user-tasks/... (internal/unstable endpoints)

Using the wrong endpoint commonly results in 503 or 404 errors.

2. Verify Zeebe Broker Health

The 503 error often indicates the Zeebe broker is unavailable or unhealthy. Check these health endpoints:

Broker Health:

http://{zeebe-broker-host}:9600/actuator/health/status

Gateway Health:

http://{zeebe-gateway}:9600/actuator/health

Both should return UP. If not, check your broker/gateway logs for errors.

3. Service Readiness in Docker

Ensure all services in your Docker setup are fully started and healthy:

  • Zeebe broker
  • Zeebe gateway
  • Tasklist
  • Identity/Keycloak

Sometimes Tasklist tries to communicate with Zeebe before it’s ready.

4. Configuration Issues

If you’re using custom context paths, ensure your rest-address configuration matches your actual deployment setup, including any context path like /zeebe.

:hammer_and_wrench: Troubleshooting Steps:

  1. Check service logs - Look at your Zeebe broker and Tasklist container logs for any errors
  2. Verify connectivity - Ensure Tasklist can reach the Zeebe broker/gateway
  3. Resource check - Make sure your containers have sufficient memory/CPU and aren’t being killed
  4. Network issues - Verify there are no network connectivity problems between services

:clipboard: Need More Help?

To better assist you, could you please share:

  • Your exact Camunda 8 version (format: major.minor.patch)
  • Which API endpoint you’re using to complete the task
  • Any relevant logs from Zeebe broker and Tasklist containers
  • Your Docker Compose configuration (if applicable)

References:

Let me know what you find with the health checks and I can help you dig deeper! :wrench: