script.fail

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

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, 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.

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

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

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

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: stop immediately but mark the run as succeeded.
• script.abort: record a failure but let the current function finish.
• process.reject: reject one record in data() and carry on with the next.