---
title: Jobs - Concepts
description: Key concepts of Scaleway Serverless Jobs.
tags: jobs serverless-jobs definition glossary execution run
dates:
  validation: 2026-05-28
  posted: 2023-11-07
---
import ServerlessConcepts from '@macros/serverless/serverless-concepts.mdx'

## Commands and arguments

The field `command` is deprecated in `v1alpha1` in favor of `startup_command` and `args` in `v1alpha2`.

For more details see [startup command and arguments](/serverless-jobs/concepts/#startup-commands-and-arguments) and [v1alpha2 migration guide](/serverless-jobs/reference-content/v1alpha1-to-v1alpha2/).

## Container Registry

Container Registry is the place where your images are stored before being deployed. We recommend using Scaleway Container Registry for optimal integration. See the [migration guide](/serverless-jobs/api-cli/migrate-external-image-to-scaleway-registry/) for full details.

## Environment variables

An environment variable is a variable whose value is set outside the program, typically through functionality built into the operating system. An environment variable is made up of a name/value pair, and any number may be created and available for reference at a point in time.

## Ephemeral storage

In addition to CPU and RAM, Serverless Jobs also provide a storage volume for the duration of the task. This storage space allows to hold the data retrieved by the job, and disappears once the execution is complete.

## Exit code

An exit code is an integer returned by a process when it finishes running. A value of `0` indicates success, while any non-zero value indicates an error. For Serverless Jobs, the exit code of a [job run](#job-run) determines its outcome:

- **`0`** — the job run succeeds.
- **Non-zero** — the job run reaches the `failed` status, which may trigger a [retry](#retries) if the configured retry count is greater than zero. See [Reason](#reason) (`exited_with_error`) for more information about non-zero exit codes.
- **`null`** — the exit code is not set when the job run fails before the container process runs or exits. The job run still reaches the `failed` status, but no exit code is returned by the runtime. This typically happens for reasons such as `image_not_found` or `technical_error`.

## GB-s

Unit used to measure the resource consumption of a container. It reflects the amount of memory consumed over time.

## Job

Serverless Jobs is a fully managed solution that enables you to plan, schedule, queue and run batch processing workloads without worrying about provisioning and scaling. A job is a single instance of one of these batch processing workloads.

## Job definition

A Job definition is a template for a Serverless Job. It contains all the information necessary to run the job, including the container image used, the resources allocated, and the command to execute. The definition acts as a blueprint for [job runs](#job-run).

## Job name

The name of a job is part of the [job definition](#job-definition) and is used for informational purposes only.

## Job run

A job run is the execution of a job definition. It can be in a running, succeeded, canceled, or failed status. Each job run has a unique identifier and can be individually monitored using [Cockpit](/cockpit/quickstart/).

## Job trigger

A job trigger allows you to invoke Jobs automatically at a specific time on a recurring cron schedule. It works similarly to a traditional Linux cron job, using the `* * * * *` format. Refer to our [cron schedules reference](/serverless-jobs/reference-content/cron-schedules/) for more information. You can add multiple triggers on the same Job Definition and also set [startup commands and arguments](/serverless-jobs/concepts/#startup-commands-and-arguments) specifically for one trigger to override the default command and arguments of your job at runtime.

## Logging

Serverless offers a built-in logging system based on Scaleway Cockpit to track the activity of your resources: see [monitoring Serverless Jobs](/serverless-jobs/how-to/monitor-job/).

## Maximum duration

The maximum duration option allows you to define the maximum execution time before your job is automatically killed.

## Metrics

Performance metrics for your Serverless resources are natively available: see [monitoring Serverless Jobs](/serverless-jobs/how-to/monitor-job/).

## Private Networks compatibility

Refer to the [dedicated FAQ](/serverless-jobs/faq/#how-can-i-configure-access-to-a-private-network-or-virtual-private-cloud-vpc) for more information on Serverless Jobs compatibility with Private Networks and [Virtual Private Cloud (VPC)](/vpc/).

## Retries

Retries refer to the automatic re-execution of a failed job run. You can configure Serverless Jobs to automatically retry a job run after up to five failed attempts.

A retry is triggered when all the following conditions are met:

- The job run does not succeed and exits with an exit code other than zero.
- The maximum number of retry attempts has not been reached.

Note that `succeeded` and `failed` are **final** statuses. When a retry is configured and the job run encounters an error during execution, it does not transition through `failed` first. Instead, it goes directly from `running` to `retrying`, and only reaches `failed` once all retry attempts are exhausted (or `succeeded` if a retry succeeds). This means a job run that will be retried never passes through the `failed` status between attempts.

[Learn how to manage the retry attempts of a Serverless Job.](/serverless-jobs/how-to/manage-job-retries/)

## Schedule (deprecated)

Job scheduling is deprecated in favor of [Job triggers](#job-trigger). Existing schedules remain active and associated jobs will continue to be invoked.

<ServerlessConcepts />

For more details about advantages of using Serverless, [read the Serverless overview page](/serverless-jobs/reference-content/serverless-overview/).

## Secrets reference

A secret reference is a mechanism that allows you to use a secret stored in [Secret Manager](/secret-manager/) within Serverless Jobs. It allows you to securely reference sensitive data, such as API secret keys, passwords, tokens, or certificates.

## Startup commands and arguments

Serverless Jobs allows you to customize the `startup_command` and `args` instructions to override default image instructions.

<Message type="note">
  * The field `command` is deprecated in favor of `startup_command`.
  * If `startup_command` is already filled then the `command` instruction is ignored.
  * `startup_command` and `args` can interpret environment variables, allowing for easier automations.
</Message>

- The `startup_command` instruction defines the command, process, or script executed when your job starts. It overrides the `ENTRYPOINT` of the image.
- The `args` instruction defines the arguments passed to the `startup_command` instruction. Arguments can be passed as environment variables, as shown in the example below.

**Example:**

```yaml
env:
- name: MESSAGE
  value: "hello world"
startup_command: ["/bin/echo"]
args: ["$(MESSAGE)"]
```

Refer to the [official Kubernetes documentation](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/) for more information on commands and arguments behavior.

## Status

A Serverless Job run can have the following statuses, grouped into **transient statuses** (the job run is still progressing through its lifecycle) and **final statuses** (the job run has reached a terminal status and will not change anymore):

### Transient statuses

* **`initialized`**: The job has been created in the system but has not yet entered the processing pipeline.
* **`validated`**: The job configuration and resources have been verified and are ready for scheduling.
* **`queued`**: The job is waiting for compute resources to become available.
* **`running`**: The job run is currently being executed.
* **`interrupting`**: A request to stop the job (via user action or system preemption) is currently being processed.
* **`retrying`**: The job run encountered an error during execution and is being automatically re-executed, based on the configured retry policy. Note that the job run transitions directly from `running` to `retrying` — it does not pass through `failed`, which is a final status only reached when all retry attempts are exhausted. See [Retries](#retries) for more information.

### Final statuses

* **`succeeded`**: The job has successfully completed.
* **`failed`**: The job run finished with an error, see [Reason](#reason) for detailed information about the error. [Check our troubleshooting documentation](/serverless-jobs/troubleshooting/job-in-error-state/) to solve the issue. 
* **`interrupted`**: The job was stopped before it could finish naturally, see [Reason](#reason) for details about the interruption.

Typical successful flow is: `initialized -> validated -> queued -> running -> succeeded`.

When retries are configured, a job run that errors during execution transitions directly from `running` to `retrying` (not through `failed`, which is a final status), then is re-executed: `initialized -> validated -> queued -> running -> retrying -> queued -> running -> succeeded`. Only when all retry attempts are exhausted does the job run reach the final `failed` status: `initialized -> validated -> queued -> running -> retrying -> queued -> running -> ... -> failed`.

### Reason

When a Job Run is in `failed` or `interrupted` state, the **Reason** field will be filled to give additional details.

### Configuration and permissions

These errors typically occur even before the job starts running, often due to setup issues.

* **`invalid_request`**: The job configuration contains malformed parameters or incompatible settings.
* **`image_not_found`**: The specified container image could not be found. Check your image path and registry permissions.
* **`invalid_image`**: The image was found but could not be run (typically when it's built for the wrong CPU architecture, must be `amd64`).
* **`secret_not_found`**: A secret referenced in your environment variables does not exist in the Secret Manager.
* **`secret_disabled`**: The required secret exists but is currently in a disabled state.

### Resource Limits
These errors occur when the job hits a defined ceiling for resources or billing.

* **`memory_usage_exceeded`**: The job was terminated because it attempted to use more RAM than allocated.
* **`storage_usage_exceeded`**: The job exceeded the allocated limit for local ephemeral storage.
* **`quota_exceeded`**: The job could not run because your project has reached its resource limits. Check [Quotas documentation](/organizations-and-projects/additional-content/organization-quotas/#serverless-jobs)

### Runtime and lifecycle
These errors occur during the actual execution of your code.

* **`exited_with_error`**: The application inside the container finished, but returned a non-zero exit code.
* **`timeout`**: The job exceeded the maximum execution time configured for the run.
* **`cancellation`**: The job run was manually terminated by a user or via an API request.
* **`technical_error`**: An internal platform issue occurred. If this persists, contact support.

## Stateless

Refers to a system or application that does not maintain any persistent state between executions. In a stateless environment, each request or operation is independent, and no information is retained from previous interactions.

This means that each request is treated as a new and isolated event, and there is no need for the system to remember previous states or data once a task is completed. Statelessness is commonly used in serverless architectures where each function execution is independent of others.

To store data you can use [Scaleway Object Storage](/object-storage/), [Scaleway Managed Databases](/managed-databases-for-postgresql-and-mysql/), and [Scaleway Serverless Databases](/serverless-sql-databases/).

## Terraform/OpenTofu

Terraform is an infrastructure-as-code tool developed by HashiCorp, while OpenTofu is an open-source fork of Terraform. Serverless Jobs integrate easily with your infrastructure as code, via our [Terraform/OpenTofu provider and resources](https://registry.terraform.io/providers/scaleway/scaleway/latest/docs/resources/job_definition).

Examples using Terraform/OpenTofu can be found in our [Serverless Examples repository](https://github.com/scaleway/serverless-examples), such as our [example using Terraform/OpenTofu with Serverless Jobs](https://github.com/scaleway/serverless-examples/blob/main/jobs/terraform-hello-world).

## vCPU-s

Unit used to measure the resource consumption of a container. It reflects the amount of vCPU used over time.