---
url: /process-functions/script-fail.md
description: >-
  Stops the process immediately and marks the run as failed, showing the given
  reason.
---

# script.fail

Stops the process immediately and marks the run as failed, showing the given reason.

```js
script.fail(reason)
```

## Parameters

| Parameter | Type | Description |
|---|---|---|
| `reason` | `string` | Why the process failed. This is shown to the user and written to the process log. |

## How it stops the process

`script.fail` is a hard stop. The moment it is called:

* The rest of the current function (`pre`, `begin`, `data` or `end`) does not run.
* No further `data(record)` rows are processed.
* `end()` does not run.
* Any rows still queued in a batch are not flushed.

The run is reported as aborted, with `reason` as the message.

This is the difference from [script.abort](/process-functions/script-abort), which records a reason but lets the current function keep running until it returns. Use `script.fail` when continuing would do damage or waste time, such as writing to the wrong period or loading a file with the wrong layout.

::: warning Don't catch it
`script.fail` works by throwing. If it is called inside a `try` block whose `catch` swallows the error, the process will not stop. Call it outside the `try`, or rethrow from the `catch`.
:::

## Examples

### Stop when required configuration is missing

```js
function begin() {
    const rate = cube.get("Rates", "2026", "Jan", "USD");

    if (rate === null || rate === "" || rate === 0) {
        script.fail("No USD rate configured for Jan 2026, cannot continue.");
    }

    // Only runs when a rate was found
    script.log("Using USD rate " + rate);
}
```

### Check a file before loading it

```js
function begin() {
    const reader = datasource.csvRead("uploads/actuals.csv", 0);

    if (reader === null) {
        script.fail("uploads/actuals.csv could not be opened.");
    }

    const first = reader.read();
    if (first === null || first.amount === undefined) {
        script.fail("actuals.csv has no 'Amount' column. Check the export layout.");
    }

    reader.close();
}
```

### Fail from inside a try/catch

```js
function begin() {
    let rates = null;

    try {
        const response = web.get("https://api.example.com/rates", {});
        rates = JSON.parse(response.body);
    } catch (err) {
        // Don't call script.fail in here - the catch would swallow it
        script.log("Could not parse rates: " + err.message);
    }

    if (rates === null) {
        script.fail("Exchange rate service did not return valid data.");
    }
}
```

## Related

* [script.complete](/process-functions/script-complete): stop immediately but mark the run as succeeded.
* [script.abort](/process-functions/script-abort): record a failure but let the current function finish.
* [process.reject](/process-functions/process-reject): reject one record in `data()` and carry on with the next.