Troubleshoot a stuck or failed workflow

Start with the pipeline ID, stage ID, application, handler, timestamp, and error code. Save the run URL before changing state. A business identifier from context often connects the workflow to the external system that can confirm whether an action already happened.

The Docker stack does not start

From the repository root, inspect the configuration you actually started:

docker compose --env-file .env -f infra/compose/docker-compose.build.yml ps -a
docker compose --env-file .env -f infra/compose/docker-compose.build.yml logs --tail=100 pipelogiq-migrate
docker compose --env-file .env -f infra/compose/docker-compose.build.yml logs --tail=100 pipelogiq-worker

For registry deployment, substitute docker-compose.registry.yml. Inspect API logs locally when needed; the first-start log can contain the generated administrator password.

Do not remove volumes or clear migration history as a first troubleshooting step. Those actions can destroy the evidence and state you need to recover.

I cannot sign in or see my run

For a new installation, use ADMIN_EMAIL and the one-time password generated on first account creation. Restarting an existing account does not generate another password. Ask an administrator to check active status or reset the account, or use the deployment owner's controlled recovery process in access.

Repeated sign-in attempts can return 429. Wait for the retry window and check the credentials before trying again. A reverse proxy can cause several people to share the same observed network identity; investigate proxy configuration rather than increasing attempts.

If sign-in works but no pipelines appear, check application membership. All roles, including Admin, need assigned workflow-data access. A 404 for a known run can mean the caller lacks access. Missing action controls can be normal Viewer behavior.

The pipeline stays NotStarted or Pending

1. Check whether the pipeline is Paused.
2. Inspect earlier stages and explicit dependencies for failure, approval wait, or work still running.
3. Confirm the Pipelogiq orchestration worker is healthy.
4. Ask an administrator to check the application's registered workers, last heartbeat, and supported handlers.
5. Compare the pipeline's stageHandlerName with the worker's registration exactly.
6. Check broker connectivity and queue naming using the bootstrap response.

The orchestration worker included in Docker does not implement your business handlers. A healthy server can accept a run whose handler has no consumer. Start the appropriate SDK/application worker.

For a clean local validation, run bash scripts/http-worker-smoke.sh after installation. It should finish a two-stage run with one retry. Avoid using the smoke handler or synthetic workflow as evidence that unrelated business handlers are healthy.

A schedule did not create a pipeline

Open its run history and read the outcome. Skipped/NoWorker means no live application worker was available at the tick. Skipped/Overlap means the overlap policy prevented another run. Catch-up policy and a paused/archived schedule also explain missing work.

Created confirms pipeline creation, not completion. Follow its pipeline link. Confirm the cron time zone and daylight-saving behavior, and check that the application worker supports the definition's handlers. Resuming a paused schedule plans from now; it does not repay all ticks missed during the pause.

Retries did not happen

Inspect the reported errorCode, retryable, retry count, and next retry time. The stage-options path needs positive maxRetries and retryInterval. A nonempty retry-code list must match. Terminal business/validation errors and retryable:false stop automatic retries.

Ask an administrator to inspect effective action policies. A matching retry policy overrides stage options, and a policy filter mismatch intentionally ends retry eligibility. Correct the cause before using Rerun stage; see reliability.

The stage is Throttled or WaitingForApproval

Throttled means dispatch was delayed by policy; inspect its next retry time and effective rate rule. Increasing worker replicas does not remove the policy.

WaitingForApproval means the application must submit an approval/rejection decision using the SDK/API. The dashboard displays this state but has no approve/reject action. Repeated decisions must agree with the recorded decision and reason. Ask the application owner to check its approval integration.

The API request timed out after creating work

Do not invent a new idempotency key. Look up or repeat the request using the original key. A returned existing pipeline is the expected recovery result. A 409 indicates that the same key now represents different intent; compare the original request rather than retrying repeatedly.

If a handler's external action timed out, inspect the external system before rerunning the handler. An unknown response does not prove the action failed.

A custom HTTP worker gets an error

Result 202 is broker acceptance, not synchronous completion. Wait for the execution state to update. With multiple API replicas, delivery tokens need the same process that holds them; do not assume an arbitrary load-balancer route will acknowledge them correctly.

No metrics, trace, or alert appears

API metrics are on the dedicated internal 9091 listener; worker metrics are on 9090. Registry Compose does not publish them to the host. Trace export needs a reachable collector and configured sampling; saving an integration alone does not restart the exporter. Alert delivery currently supports Telegram and generic webhook. Confirm a test at the destination and inspect deduplication behavior.

See observability for addresses and configuration.

Share a useful incident report

Include version, deployment type, sanitized error text, run/stage IDs, handler name, relevant timestamps, observed/expected behavior, and whether the external action already occurred. Include the smallest relevant log excerpt. Remove passwords, application keys, session tokens, connection strings, and sensitive payloads. Preserve the original run instead of deleting it while investigating.