---
title: Troubleshooting
description: Diagnose common runtime issues and resolve them quickly.
order: 84
---

# Troubleshooting

Use this page to debug common issues in local and production environments.

## Jobs are not executing

- Confirm worker process is running.
- Confirm job is registered and discoverable.
- Check run status via `IDurableJobRunQueryService`.
- Verify provider connection and migrations completed.

## Unexpected retry behavior

- Verify `MaxAttempts` for the job.
- Check `RetryBehavior`, delay, and jitter settings.
- Confirm exception path actually throws when retry is desired.

## Lease contention or duplicate-appearing work

- Confirm unique `WorkerName` per process/container.
- Validate `LeaseDurationSeconds` is not shorter than typical execution time.
- Review long-running handlers for heartbeat extension timing risks.

## Missing telemetry or hosted observability data

- Confirm `Eventing.TenantId` and `Eventing.ClientSecret` are set.
- Verify outbound connectivity to ingestion API.
- Trigger a known run and confirm event flow end to end.

## Runtime commands are not applying

- Confirm worker is running with `Eventing.RuntimeControlEnabled=true`.
- Verify `Eventing.IngestionApiBaseUrl` points at the API environment that hosts runtime control.
- Confirm worker can reach `Eventing.RuntimeControlSyncPath` (default `/v1/runtime/control/sync`).
- Check that tenant credentials (`Eventing.TenantId`, `Eventing.ClientSecret`) match the tenant where commands are issued.
- Ensure target schedule exists with the same `jobName` used by the command payload.

## Command appears in history but failed

- `schedule_not_found`: command referenced a job name not present in worker registration.
- `invalid_payload`: required fields were missing (`jobName`, `enabled`, `cronExpression`, `timeZone`).
- `unsupported_command_type`: runtime version does not support the command type sent.
- `schedule_run_blocked`: run-now was rejected by schedule/runtime guard conditions.

If failures persist, compare runtime package version and hosted platform feature expectations to ensure they are aligned.