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.