Process Properties

This page summarizes all built-in task properties available in Nextflow process bodies. These properties provide information about the current task execution and can be used in scripts, directives, and dynamic expressions.

---

Task Identification

Properties that uniquely identify the task or its context.

task.id

The pipeline-level task index (corresponds to task_id in the execution trace).

process splitById {
    input:
    path sample
    script:
    """
    # Use task.id to create unique output folders for each pipeline task
    mkdir output_${task.id}
    cp $sample output_${task.id}/
    """
}

task.index

The process-level task index.

process nameFilesByIndex {
    input:
    path input_file
    script:
    """
    # Use task.index to generate sequentially named files
    cp $input_file result_${task.index}.txt
    """
}

task.name

The current task name. Available only in exec: blocks.

process logTaskName {
    exec:
    // Use task.name to write a log entry for each task
    new File("task_log.txt") << "Started: ${task.name}\n"
}

task.process

The current process name.

process addProcessNameToOutput {
    script:
    """
    # Add process name to output file for traceability
    echo "Generated by process: ${task.process}" > process_info.txt
    """
}

task.hash

The unique hash ID for the task. Available only in exec: blocks.

process cacheByHash {
    exec:
    // Use task.hash to create a cache directory for each unique task
    def cacheDir = new File("/tmp/cache/${task.hash}")
    cacheDir.mkdirs()
    // ... store intermediate results in cacheDir ...
}

task.workDir

The unique working directory for the task. Available only in exec: blocks.

process saveLogToWorkDir {
    exec:
    // Save a log file in the task's work directory
    new File("${task.workDir}/run.log") << "Task started at ${new Date()}\n"
}

---

Task Attempts & Retry

Properties related to task attempts and retry logic.

task.attempt

The current attempt number for the task.

process retryDoubleResources {
    errorStrategy 'retry'
    maxRetries 4
    cpus { 2 ** (task.attempt - 1) }
    memory { (4 * (2 ** (task.attempt - 1))) + ' GB' }
    script:
    """
    # Double CPUs and memory on each retry attempt
    echo "Attempt: ${task.attempt}, CPUs: ${task.cpus}, Memory: ${task.memory}"
    ./run_analysis.sh
    """
}

See also: Directives.md errorStrategy and maxRetries for configuring the retry behavior that drives task.attempt.

task.previousException

New in version 24.10.0 The exception reported by the previous task attempt. Accessible only when retrying a failed task (task.attempt > 1).

process retryWithException {
    errorStrategy 'retry'
    maxRetries 2
    script:
    """
    # If retrying, log the previous exception for debugging
    if [[ ${task.attempt} -gt 1 ]]; then
      echo "Previous error: ${task.previousException}" >> error.log
    fi
    ./run_analysis.sh
    """
}

task.previousTrace

New in version 24.10.0 The trace record associated with the previous task attempt. Accessible only when retrying a failed task (task.attempt > 1). Useful for accessing previous runtime metrics.

process retryWithTrace {
    errorStrategy 'retry'
    maxRetries 2
    script:
    """
    # If retrying, adjust resources based on previous usage
    if [[ ${task.attempt} -gt 1 ]]; then
      echo "Previous memory usage: ${task.previousTrace?.memory}" >> resource.log
      # Optionally, use this info to tune parameters
    fi
    ./run_analysis.sh
    """
}

---

Task Execution Status

Properties related to the execution result and directives.

task.exitStatus

The exit code of the task script (only for script: or shell: blocks). Available after the script has executed.

process checkExit {
    errorStrategy { task.exitStatus == 1 ? 'retry' : 'finish' }
    script:
    """
    # Simulate a command that may fail
    ./run_step.sh || exit 1
    """
}

---

Directive Values

Beyond the properties above, the resolved value of any directive for the current task is available via task.<directive> (e.g. task.cpus, task.memory, task.attempt-driven values). This is how dynamic directives can reference their own previous or sibling values, as in the task.attempt example above.

See also: Directives.md for the full list of directives whose resolved values are available this way.