5. Troubleshooting and Best Practices

What to check when a process does not behave, and habits that keep Camunda 8 projects healthy. Related: Writing Job Workers, BPMN Modelling Guide, DMN and FEEL, Architecture.

First question: where is the instance?

Open Operate, find the instance, and look at the token: where is it, and is there a red incident marker?

flowchart TD
    A["Instance not progressing"] --> B{"Incident shown in Operate?"}
    B -- yes --> C["Read the error message, fix the cause, then Retry"]
    B -- no --> D{"Where is the token?"}
    D -- "service task" --> E["Is a worker running with the exact job type?"]
    D -- "user task" --> F["Check Tasklist: assignee, candidate groups, form"]
    D -- "message catch event" --> G["Was the message published with the right name and correlation key?"]
    D -- "timer" --> H["Check the duration expression and wait time"]
    D -- "gateway" --> I["Check conditions and variable values"]

Common problems

Reading incidents

In Operate: open the failed instance, click the incident marker to see the error type and message, then: 1. Fix the cause (the worker, data or model). 2. If the data is wrong, edit the variable on the instance. 3. Press Retry on the incident. 4. If the instance is hopeless, cancel it, or use modify instance to move the token.

Never just cancel instances to make the red go away without understanding why they failed.

Testing

Run these in your pipeline (GitHub Actions) before deploying a model.

Deploying changes

• Keep models, decisions and forms in Git with the worker code; review them like code.
• Deploy from CI, not by hand, to test and production clusters (CI/CD Pipelines).
• Each deployment of a changed model creates a new version. Running instances keep their version, so you can change a process safely, but design variables to stay backward compatible.
• To move running instances onto a new version, use process instance migration.
• Do not rename job types or message names casually: a worker or sender somewhere may depend on them.

Best practices

Process design - Model what happens and when; keep calculation and integration in workers and rules in DMN. - One business process per diagram; extract reusable parts as call activities. - Name things clearly and keep the happy path straight (style guide). - Every service task should have a thought-out failure story: retry, error path or manual review. - Add timers/escalations for waiting on people so nothing sits forever.

Data - Keep variables small and structured; store documents elsewhere and pass references. - Document the variables each task reads and writes. - Never put secrets or unnecessary personal data in variables (they appear in tools and exports).

Operations - Monitor the engine, the search store, worker health and job backlog; alert on incidents. - Set retention on historic data so storage does not grow forever. - Back up broker volumes and the search store; test restores. - Run several workers per job type and several brokers; plan upgrades. - Use separate clusters for development, test and production, with different credentials.

Teams - Agree on naming conventions (job types in kebab-case or snake_case, one style). - Review models with the business: if they cannot read it, simplify it. - Keep a README per process: purpose, owner, variables, workers, decisions and message names.

Anti-patterns

Useful checks in a hurry

$ ./c8run start                            # is the local stack up?
$ curl -s localhost:9600/actuator/health   # Camunda health endpoint (management port; check your version)
$ docker compose logs -f                   # Compose setups: watch broker and worker logs
$ grep -r "taskDefinition type" models/    # list every job type used in your models