Troubleshooting

The 20 most common issues encountered when using Priostack, with causes and step-by-step fixes.

Authentication and Authorization

Problem	Cause	Fix
401 Unauthorized on every request	Missing or invalid `X-API-Key` header, or the key was rotated/deleted.	Check your key in Console → Settings → API Keys. Ensure the header name is exactly `X-API-Key` (case-insensitive). Verify the environment variable is set: `echo $PRIOSTACK_API_KEY`.
403 Forbidden on admin endpoint	Using a standard API key on an endpoint that requires the admin key.	Admin endpoints (`/api/admin/*`) require the `ADMIN_KEY`. Check Console → Settings for your admin key. Do not use your regular API key for admin operations.

Credits and Billing

Problem	Cause	Fix
402 Payment Required when starting instance	Credit balance is zero.	Free credits refresh every month; the balance is shown in Console → Billing. Your balance is shown on the Console dashboard. Subscribe to the `credits.low` webhook to get notified before exhaustion.
Credits deducted but process didn't start	The BPMN parsed successfully and a credit was charged, but a runtime error immediately created an incident (e.g., missing required variable).	Check Console → Incidents for the new instance. Resolve the incident and re-trigger the process. Note: credits are not refunded for incidents.

Job Workers

Problem	Cause	Fix
Job not activating (long poll returns empty)	The `type` in your activate request doesn't match the `zeebe:taskDefinition type` in the BPMN.	Check the BPMN XML for the exact task type string. Types are case-sensitive. Use the Console to inspect the deployed process definition.
Job activated twice by different workers	Your worker processed the job but failed to call complete before the job deadline expired.	Ensure your processing time is shorter than the job deadline. Increase the deadline via `zeebe:taskDefinition retries="3"` or reduce processing time. Make your handler idempotent using the job key for deduplication.
Job stuck in "active" state	Worker activated the job but crashed before completing or failing it.	The job deadline will expire and the job will return to the queue (typically after 30 minutes). You can manually fail the job via the Console → Process Instance → Jobs panel to accelerate this.

Process Execution

Problem	Cause	Fix
Process instance stuck (no incident)	Instance is waiting at a Message Catch Event, Timer, or User Task with no worker or user to advance it.	Check Console → Process Instance to see the current element. For message waits: send the correlated message. For timers: check the timer definition. For user tasks: assign and complete via Tasklist.
BPMN parse error on deploy	Invalid XML syntax, missing required attributes, or unsupported BPMN elements.	Validate your BPMN in the Designer before deploying. Check the error response body for specific element IDs and missing attributes.
Process not starting (200 OK but instance never appears)	Race condition in monitoring, or the instance completed immediately (e.g., no tasks).	Check `GET /v1/process-instances?state=COMPLETED` — the instance may have completed instantly. Add a small delay before querying, or use webhooks for reliable notification.
Exclusive gateway: "no sequence flow with true condition"	None of the outgoing sequence flow conditions evaluated to true, and no default flow was defined.	Add a default flow (flow without a condition, marked with a slash in BPMN diagrams) to handle the catch-all case. Ensure all possible variable states are covered.

DMN and FEEL

Problem	Cause	Fix
DMN decision not found	The `decisionId` in the Business Rule Task doesn't match the deployed DMN decision.	Check the `id` attribute of the `<decision>` element in your DMN file. IDs are case-sensitive. Redeploy if necessary.
FEEL evaluation error: variable not found	A FEEL expression references a variable that isn't set on the process instance at that point.	Check the process flow to ensure the variable is set before the FEEL expression is evaluated. Use the FEEL Playground to test expressions with sample values.
DMN hit policy UNIQUE: multiple rules matched	Two or more rules in the decision table match the input, but the hit policy requires exactly one match.	Review your decision table rules — they should be mutually exclusive when using UNIQUE. Add more specific conditions or switch to FIRST hit policy.

Webhooks

Problem	Cause	Fix
Webhook not firing	Webhook URL is not registered, or the endpoint is returning non-2xx status.	Check Console → Settings → Webhooks for your registered URL. Check the delivery log for failed attempts. Ensure your endpoint returns 200 within 10 seconds.
Webhook signature verification failing	Using a framework that parses the body before you can read it raw (Express with JSON middleware).	Read the raw body bytes before any parsing. In Express, use `express.raw()` instead of `express.json()` for the webhook route.

Performance and Limits

Problem	Cause	Fix
429 Too Many Requests	Exceeding 300 requests/minute per API key.	Implement retry with backoff using the `X-RateLimit-Reset` header. Use long-polling for job activation (counts as 1 request per 30s). See Rate Limits.
Memory issues with large variable payloads	Storing large binary data or large arrays in process variables.	Store large data externally (S3, database) and pass only the reference (URL, ID) as a process variable. Keep individual variable values under 1 MB.
Slow process instance queries	Querying thousands of instances without filtering.	Add state filters (`?state=ACTIVE`) and pagination (`?limit=50&offset=0`) to instance queries. Use webhooks for real-time notifications instead of polling.

Still stuck? Check the FAQ, search the Community Forum, or open a support ticket from the Console. Include your X-Request-ID header value from the failed request.