Introduction

startingDeadlineSeconds is the amount of lateness Kubernetes will tolerate for a scheduled CronJob run. If the controller notices that a run was missed only after that deadline has passed, it skips that run instead of starting it late.

What It Controls

CronJobs are driven by the Kubernetes controller. A run can be delayed because of controller downtime, API issues, scheduling lag, or concurrency rules. This field answers one question: if the exact schedule time was missed, how long is that run still worth starting?

Suppose a job should start at 10:00:00 and startingDeadlineSeconds is 30. If the controller catches up at 10:00:20, it may still create the job. If it notices only at 10:00:45, that scheduled run is too old and gets skipped.

Example

1apiVersion: batch/v1
2kind: CronJob
3metadata:
4  name: report-job
5spec:
6  schedule: "*/5 * * * *"
7  startingDeadlineSeconds: 60
8  jobTemplate:
9    spec:
10      template:
11        spec:
12          restartPolicy: OnFailure
13          containers:
14            - name: report
15              image: busybox
16              command: ["sh", "-c", "date; echo run"]

In this example, each scheduled run has a one-minute grace period. After that, the missed run is abandoned and Kubernetes waits for the next schedule.

Why It Exists

Sometimes late execution is worse than no execution. A billing export, cleanup task, or windowed aggregation job may stop making sense if it starts much later than planned. startingDeadlineSeconds lets you tell Kubernetes not to replay stale work indefinitely.

If delayed execution is still useful, you can leave the field unset or choose a larger value. If stale jobs are dangerous, choose a smaller value.

Interaction with concurrencyPolicy

This field matters more when concurrencyPolicy is restrictive. With Forbid, Kubernetes will not start a new run while the previous one is still active. That blocked run can become a missed schedule. If it remains blocked until the deadline passes, Kubernetes skips it entirely.

So the field is not only about cluster outages. It also affects overlapping schedules when jobs run longer than expected.

What It Does Not Mean

startingDeadlineSeconds does not control how long a job may run. It does not set pod timeout behavior, retry counts, or backoffLimit. Those settings apply after a job starts. This field only decides whether a missed scheduled run should still be created.

Choosing a Value

Pick a value based on business meaning, not guesswork:

• small value if stale runs should be dropped quickly
• larger value if catching up is acceptable
• unset if there is no strict lateness cutoff

Be careful not to set it so low that normal control-plane jitter causes accidental skips.

Teams usually pick this value after watching real cluster behavior for a while. If jobs commonly start a few seconds late during normal load, an overly strict deadline will create avoidable skips that look like failures even though the control plane is still operating normally.

Common Pitfalls

• Treating it like a runtime limit for the job itself.
• Assuming it controls retries for failed jobs.
• Setting it too low and then misreading skipped runs as random failures.
• Forgetting that concurrencyPolicy: Forbid can turn overlap into missed schedules.
• Expecting Kubernetes to replay every missed run forever.

Summary

• 'startingDeadlineSeconds is a lateness cutoff for starting a missed CronJob run.'
• If the controller notices the missed schedule before the deadline, the run may still start.
• If the deadline has passed, Kubernetes skips that run.
• It affects missed schedules, not execution time or retry count.
• Choose the value based on whether late execution is still meaningful for the workload.