---
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 runtime query APIs (`IDurableJobRunQueryService` in .NET, runtime run-query methods in Node.js).
- 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 commands are being sent from the Observation Jobs page for the correct tenant.
- Confirm worker is running with `Eventing.RuntimeControlEnabled=true`.
- Verify `Eventing.IngestionApiBaseUrl` points at the same environment used by Observation.
- Check that tenant credentials (`Eventing.TenantId`, `Eventing.ClientSecret`) match the tenant where commands are issued.
- Ensure target schedule exists and is visible in the Jobs page for the selected tenant.

## Command appears in history but failed

- `schedule_not_found`: command targeted a schedule name not present in worker registration.
- `invalid_payload`: command data was incomplete or malformed.
- `unsupported_command_type`: runtime version does not support that command yet.
- `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.