Troubleshoot
Start from the run detail: the Error column of the failed step, then the Log. Run again with Run with parameters at DEBUG to see the SQL of every query.
A run shows FAILED
| Error in the step row | Usual cause |
|---|---|
| step timed out after N s | The step exceeded its timeout_seconds (3 600 by default). Raise it in jobs.toml, or split the work. |
| → 404, → 500 (http step) | The called URL answered with that status. |
| A database error | Wrong credentials, a missing table, a constraint. Test the pool in Liberty Next → Administer → Pools and the query on the connector page. |
| cannot import module … / has no attribute … (python step) | The plugin is not where callable says, or the server was not restarted after a change — see Deploy and debug. |
| period … is closed (file_load) | The step's refuse query rejected the load on purpose. |
| control total mismatch … (file_load) | The loaded total differs from the expected one; nothing was written. |
After fixing, rerun only the failed step: Run with parameters, untick the steps that already succeeded, Run.
A step succeeded but did the wrong thing
Look at Rows affected and at the step's details, then rerun at DEBUG: the log shows each query with its values. For a file_load, compare read / inserted / rejected and download the rejected rows.
A run stays RUNNING
A step waits on something slow — a locked table, a remote API, a long sync. Each step stops at its timeout_seconds, the job at its own (4 hours by default). Cancel on the job's card stops it sooner.
Cancel doesn't stop my step
SQL, HTTP, file-load and async Python steps stop at once. A Python function written with def runs in a worker thread that cannot be interrupted: the run shows CANCELED, but the function goes on until it returns. Write long functions as async — see Write a callable.
The schedule doesn't fire
| Check | Fix |
|---|---|
| The card shows disabled or Manual only | Switch the job on, or give it a schedule. |
| The day is wrong | The scheduler counts the days of the week from 0 = Monday. Write mon-fri, not 1-5 — see Schedules. |
| The Next runs preview is not what was expected | Fix the cron or the timezone. |
| The server was down at that time | The run is recorded MISSED; run it by hand. |
The job is missing from the list
jobs.toml was edited by hand and no longer validates: the server log names the error. A key not in the schema is refused — check the spelling against Steps and Create a job. After fixing the file, Reload config (at the top of any Liberty Next editor page).
The log is empty
The run's log level is WARNING, or a Python plugin logs under a namespace that is not registered — see Custom Python steps.
403 on the Jobs page
The Nomaflow pages and their API are reserved to superusers.