503 Service Unavailable when completing usertask

Charles_Andrea · August 12, 2025, 6:27am

Hello guys.
I use camunda 8, selfmanaged in docker in local.
I receive this error when I try to complete user.
Did someone encounter this issue ?

zee-bot · August 12, 2025, 7:31am

Hi there!

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:

Most Common Causes & Solutions:

1. Check Your API Endpoint

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

Correct: /v1/tasks/{taskId}/complete (Tasklist API, typically port 8082)
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.

Troubleshooting Steps:

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

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!

claudio_rio · August 12, 2025, 7:32am

According to this conversation, this endpoint is for internal use only and the complete action should be used instead.

Charles_Andrea · August 12, 2025, 12:27pm

Hey @claudio_rio.
So user have to open camunda tasklist to complete his task?
is it not accessible via api REST call?

zee-bot · August 12, 2025, 12:28pm

Great question! No, users don’t have to open Tasklist UI - you can absolutely complete user tasks programmatically via REST API calls!

Correct REST API Approach:

You should use the Tasklist REST API v1 with this endpoint:

PATCH /v1/tasks/{taskId}/complete

Not the internal endpoint that was causing your 503 error.

Complete Example:

1. Authentication First

# Get session cookie (for self-managed with basic auth)
curl -X POST 'http://localhost:8082/api/login' \
  -H 'Content-Type: application/json' \
  -d '{"username": "demo", "password": "demo"}' \
  -c cookies.txt

2. Complete the Task

# Complete task with variables
curl -X PATCH 'http://localhost:8082/v1/tasks/{taskId}/complete' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d '{
    "variables": [
      {
        "name": "approved", 
        "value": "true"
      }
    ]
  }'

Or without variables:

curl -X PATCH 'http://localhost:8082/v1/tasks/{taskId}/complete' \
  -H 'accept: application/json' \
  -b cookies.txt

Key Points:

Port: Tasklist typically runs on port 8082 (not 8080)
Authentication: You need either session cookies or Bearer tokens
Task Assignment: The task must be assigned to the user before completion
Task ID: Use the task ID from Tasklist, not the user task key from Zeebe

Alternative: Camunda 8 API (Newer)

There’s also a newer Camunda 8 API (v2) available:

POST /v2/user-tasks/{userTaskKey}/completion

But for your current setup, stick with the Tasklist v1 API as it’s more stable.

Your Original Error

Your 503 error was likely because you were using an internal endpoint or there were connectivity issues between Tasklist and Zeebe. The correct Tasklist API should resolve this!

References:

Try the correct endpoint and let me know if you still get the 503 error!

Charles_Andrea · August 12, 2025, 12:36pm

yes but when I use : PATCH http://localhost:8082/v1/tasks/2251799813699990/complete
I get :

{
“status”: 400,
“message”: “This operation is not supported using Tasklist V1 API. Please use the latest API. For more information, refer to the documentation: Migrate to Camunda user tasks | Camunda 8 Docs”,
“instance”: “dd7b02cf-aaef-4593-9afa-e7d873572126”
}

and when I use POST: http://localhost:8082/v2/user-tasks/2251799813699990/completion

I get:
{
“type”: “about:blank”,
“title”: “io.camunda.zeebe.broker.client.api.PartitionNotFoundException”,
“status”: 503,
“detail”: “Expected to handle REST API request, but request could not be delivered”,
“instance”: “/v2/user-tasks/2251799813699990/completion”
}

zee-bot · August 12, 2025, 12:38pm

Ah, now I see the issue! You’re dealing with Zeebe User Tasks (not Tasklist tasks), and the PartitionNotFoundException indicates a broker connectivity problem.

Root Cause Analysis:

V1 API Error: The 400 error confirms you’re using Zeebe User Tasks, which require the V2 API
V2 API Error: The 503 PartitionNotFoundException means the Zeebe gateway can’t reach the broker or the partition is unavailable

Immediate Troubleshooting Steps:

1. Check Zeebe Broker Health

# Check broker health
curl http://localhost:26500/actuator/health/status

# Check gateway health  
curl http://localhost:26500/actuator/health

Both should return UP. If not, your broker is the problem.

2. Verify Your Docker Services

Check if all containers are running and healthy:

docker ps
docker logs <zeebe-broker-container>
docker logs <zeebe-gateway-container>

Look for errors like:

Partition initialization failures
Memory/disk issues
Network connectivity problems

3. Check Partition Status

The error suggests partition issues. In your broker logs, look for:

Partition-1 failed, marking it as unhealthy
Services not installed
Memory or disk space errors

4. Verify Your REST Endpoint Configuration

Make sure you’re hitting the correct gateway port. The V2 API should be:

POST http://localhost:8080/v2/user-tasks/{userTaskKey}/completion

(Port 8080 for Zeebe Gateway, not 8082 for Tasklist)

Common Docker Issues:

Resource Constraints: Zeebe needs sufficient memory (at least 1GB)
Startup Timing: Gateway might start before broker is ready
Network Issues: Services can’t communicate with each other

Quick Fix Attempts:

Restart your Docker setup to ensure clean startup order
Check resource allocation for your containers
Verify network connectivity between gateway and broker

Need More Info:

Could you share:

Your Docker Compose file (or container setup)
Zeebe broker logs during startup
Output of the health check endpoints
Your Camunda version

The PartitionNotFoundException is almost always a broker health/connectivity issue, not an API problem. Let’s get your Zeebe cluster healthy first!

References:

Alex_Voloshyn · August 12, 2025, 12:54pm

Hi @Charles_Andrea
No, it means you have to use this call Complete a task | Camunda 8 Docs instead of the one that you use now. You can check the meanings of response 400 on the same page.
for example:

curl -L -X PATCH 'http://localhost:8080/v1/tasks/:taskId/complete' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TASKLIST-SESSION>' \
-H 'Cookie: TASKLIST-SESSION=%3CTASKLIST-SESSION%3E' \
-d '{
  "variables": [
    {
      "name": "string",
      "value": "string"
    }
  ]
}'

Regards,
Alex

Charles_Andrea · August 12, 2025, 12:58pm

hi @Alex_Voloshyn.
I try ```
PATCH ‘http://localhost:8080/v1/tasks/:taskId/complete’


 with the authorization but I get 

{
“status”: 400,
“message”: “This operation is not supported using Tasklist V1 API. Please use the latest API. For more information, refer to the documentation: Migrate to Camunda user tasks | Camunda 8 Docs”,
“instance”: “dd7b02cf-aaef-4593-9afa-e7d873572126”
}

zee-bot · August 12, 2025, 12:58pm

Perfect! This confirms you’re using Zeebe User Tasks (not traditional Tasklist tasks), which is why the V1 API gives you that 400 error.

The real issue is the 503 PartitionNotFoundException with the V2 API - this is a Zeebe broker connectivity problem that we need to solve.

Let’s Diagnose Your Zeebe Setup:

Since you’re getting PartitionNotFoundException, we need to check your Zeebe broker health. Can you please run these diagnostic commands and share the results?

1. Check Zeebe Health Endpoints:

# Zeebe Gateway health (usually port 26500 or 9600)
curl http://localhost:26500/actuator/health
curl http://localhost:9600/actuator/health

# Also try the ready endpoint
curl http://localhost:26500/ready

2. Check Your Docker Containers:

# List all containers and their status
docker ps

# Check Zeebe broker logs
docker logs <your-zeebe-broker-container-name>

# Check Zeebe gateway logs  
docker logs <your-zeebe-gateway-container-name>

3. Verify Your V2 API Call:

Make sure you’re using the correct port and endpoint:

# This should be Zeebe Gateway port (usually 8080), not Tasklist port (8082)
POST http://localhost:8080/v2/user-tasks/2251799813699990/completion

What We’re Looking For:

In the logs, we need to check for:

Broker successfully started and partitions initialized
Any errors about partitions, memory, or connectivity
Messages like “Partition-1 failed” or “Services not installed”

Also Share:

Your Camunda 8 version
Your Docker Compose file (or how you’re running Camunda)
Which port your Zeebe Gateway is actually running on

The PartitionNotFoundException means your gateway can’t communicate with the broker properly. Once we fix that, your V2 API calls should work!

Let’s get those diagnostic results first and we’ll solve this step by step!

Charles_Andrea · August 12, 2025, 1:01pm

here is my docker-compose.yaml:

docker-compose.yaml (18.0 KB)

and here my camunda version (in .env file)

## Image versions ##
CAMUNDA_REST_QUERY_ENABLED=true 
# renovate: datasource=docker depName=camunda/connectors-bundle
CAMUNDA_CONNECTORS_VERSION=8.7.6
# renovate: datasource=docker depName=camunda/zeebe
CAMUNDA_ZEEBE_VERSION=8.7.8
# renovate: datasource=docker depName=camunda/identity
CAMUNDA_IDENTITY_VERSION=8.7.4
# renovate: datasource=docker depName=camunda/operate
CAMUNDA_OPERATE_VERSION=8.7.8
# renovate: datasource=docker depName=camunda/tasklist
CAMUNDA_TASKLIST_VERSION=8.7.8
# renovate: datasource=docker depName=camunda/optimize
CAMUNDA_OPTIMIZE_VERSION=8.7.5
# renovate: datasource=docker depName=camunda/web-modeler-restapi
CAMUNDA_WEB_MODELER_VERSION=8.7.6
# renovate: datasource=docker depName=elasticsearch
ELASTIC_VERSION=8.17.8
KEYCLOAK_SERVER_VERSION=24.0.5
# renovate: datasource=docker depName=axllent/mailpit
MAILPIT_VERSION=v1.21.8
POSTGRES_VERSION=14.5-alpine
HOST=localhost
KEYCLOAK_HOST=localhost

## Configuration ##
# By default the zeebe api is public, when setting this to `identity` a valid zeebe client token is required
ZEEBE_AUTHENTICATION_MODE=none
ZEEBE_CLIENT_ID=zeebe
ZEEBE_CLIENT_SECRET=zecret

# Set to 'true' to enable resource based authorizations for users and groups
# This can be used to limit access for users or groups to view/update specific
# processes and decisions in Operate and Tasklist
RESOURCE_AUTHORIZATIONS_ENABLED=false

# Set to 'true' to enable multi-tenancy across all components
# This requires use of identity for authentication
#
#  ZEEBE_AUTHENTICATION_MODE=identity
#
MULTI_TENANCY_ENABLED=false

# Document store credentials
# DOCUMENT_DEFAULT_STORE_ID=...
# AWS_ACCESS_KEY_ID=...
# AWS_SECRET_ACCESS_KEY=...
# AWS_REGION=..
# DOCUMENT_STORE_AWS_BUCKET=...
# DOCUMENT_STORE_AWS_BUCKET_PATH=...
# DOCUMENT_STORE_AWS_CLASS=...

zee-bot · August 12, 2025, 1:02pm

Perfect! Now I can see your setup clearly. You’re running Camunda 8.7.8 with a standard Docker Compose configuration. Let’s diagnose the PartitionNotFoundException issue step by step.

Based on Your Configuration:

Zeebe Gateway REST API: http://localhost:8080
Tasklist API: http://localhost:8082
Your V2 API endpoint should be: http://localhost:8080/v2/user-tasks/{userTaskKey}/completion

Let’s Run Diagnostics:

1. Check All Container Status:

docker-compose ps

2. Check Zeebe Gateway Health:

# Gateway health endpoint
curl http://localhost:9600/actuator/health

# Gateway ready endpoint  
curl http://localhost:9600/ready

3. Check Zeebe Broker Logs:

# Check for any partition or startup errors
docker-compose logs zeebe

# Look specifically for these patterns:
docker-compose logs zeebe | grep -i "partition\|error\|failed"

4. Check Gateway Logs:

docker-compose logs zeebe-gateway

# Look for connectivity issues:
docker-compose logs zeebe-gateway | grep -i "partition\|error\|broker"

Common Issues in Your Setup:

Resource Constraints

Your Zeebe broker might need more memory. Try adding this to your zeebe service in docker-compose.yaml:

zeebe:
  # ... existing config
  environment:
    - ZEEBE_BROKER_DATA_DISK_FREESPACE_REPLICATION=1GB
    - JAVA_OPTS=-Xms1g -Xmx1g

Startup Timing

Gateway might be starting before broker is ready. Check if all services are fully up:

# Wait a bit after startup, then check
docker-compose logs zeebe | tail -20
docker-compose logs zeebe-gateway | tail -20

Quick Test:

Once your containers are healthy, try this exact call:

curl -X POST 'http://localhost:8080/v2/user-tasks/2251799813699990/completion' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{}'

Please Share:

Output of docker-compose ps
Output of the health check: curl http://localhost:9600/actuator/health
Any errors from: docker-compose logs zeebe | grep -i error

The PartitionNotFoundException typically means either:

Zeebe broker isn’t fully started
Network connectivity issues between gateway and broker
Resource constraints causing broker instability

Let’s get those diagnostic results and we’ll pinpoint the exact issue!

Alex_Voloshyn · August 12, 2025, 1:03pm

Have you checked the link I shared and the possible meanings for response 400?

zee-bot · August 12, 2025, 1:03pm

You’re absolutely right! I should have focused on that first. Let me clarify the 400 error properly.

The 400 Error Explanation:

The 400 error you’re getting with the V1 API is expected and correct:

{
  "status": 400,
  "message": "This operation is not supported using Tasklist V1 API. Please use the latest API..."
}

This means you’re using Zeebe/Camunda User Tasks (the new type), which cannot be managed through the Tasklist V1 API at all. The V1 API only supports the old job worker-based user tasks.

You MUST Use V2 API:

For Zeebe/Camunda user tasks, you must use:

POST http://localhost:8080/v2/user-tasks/{userTaskKey}/completion

The V1 API (/v1/tasks/...) will always give you a 400 error for Zeebe user tasks - this is by design.

So Your Real Problem Is:

The 503 PartitionNotFoundException with the V2 API. This is what we need to fix.

Let’s Focus on the V2 API Issue:

Can you please run these diagnostics to help solve the 503 error:

# Check if Zeebe Gateway is healthy
curl http://localhost:9600/actuator/health

# Check container status
docker-compose ps

# Check for Zeebe broker errors
docker-compose logs zeebe | grep -i "partition\|error"

Summary:

V1 API: Will always return 400 for Zeebe user tasks (this is correct behavior)
V2 API: This is what you need, but it’s giving 503 due to broker connectivity issues

The 400 error is telling you exactly what to do - use the V2 API. Now we just need to fix why the V2 API can’t reach your Zeebe broker!

Reference: Migration Guide - API Differences

Charles_Andrea · August 12, 2025, 1:34pm

yes, of course.

Alex_Voloshyn · August 12, 2025, 1:41pm

Charles_Andrea:

hi @Alex_Voloshyn.
I try ```
PATCH ‘http://localhost:8080/v1/tasks/:taskId/complete’

 with the authorization but I get 

{
“status”: 400,
“message”: “This operation is not supported using Tasklist V1 API. Please use the latest API. For more information, refer to the documentation: Migrate to Camunda user tasks | Camunda 8 Docs”,
“instance”: “dd7b02cf-aaef-4593-9afa-e7d873572126”
}

Shouldn’t you use port 8082 here?

Charles_Andrea · August 12, 2025, 2:06pm

8082 is the port of my tasklist service.

Alex_Voloshyn · August 12, 2025, 2:30pm

Can you share the BPMN file? What type of task do you use?

Charles_Andrea · August 17, 2025, 8:12am

hey,
here you are
{52E0949B-01DF-4FF8-B00F-B611CD867546}

it is a user task

Alex_Voloshyn · August 18, 2025, 5:30am

Could you check the implementation type, like Camunda user task or Job worker?

Regards,
Alex