Troubleshooting

The ETL Engine is not chatty on stdout. Almost every diagnostic signal arrives through the log files the engine writes during a run.

When something goes wrong

The recommended workflow when an ETL run fails:

1. Check that the engine started at all. The terminal output of run-etl-engine.sh shows the version banner and any configuration-loading errors. If you see one of those, the run never reached the mapping stage — see Common Errors.
2. Open etl-engine.log. This is the engine's own log. Errors at ERROR level here usually indicate an engine-level problem; errors at lower levels are typically about the Rabbit-in-a-Hat configuration. If the engine stopped silently with no terminal output, this is the place to look.
3. Open the per-table log for the table that failed. Each non-vocabulary CDM table has its own log under logs/, named after the CDM table. The trailing [critical] Errors break ETL of table line tells you the table failed to load; the actual cause is one or more earlier [error] lines in the same file.
4. Raise the log level if you need more detail. Set logging.log level to DEBUG or TRACE in etl.conf and re-run. See Log Files.
5. Use TraceWhen for surgical debugging of one specific source row that's misbehaving.

Pages

• Log Files — what each log contains and how to read them.
• Common Errors — frequently seen messages and how to resolve them.
• Performance Tuning — knobs that affect throughput.
• TraceWhen — per-record verbose logging for targeted debugging.

Getting help

Issues that turn out to be engine bugs (rather than mapping issues) should be reported to your Rook IT contact, with:

• The engine version (printed at the start of etl-engine.log).
• A copy of etl.conf.
• The relevant table's log file.
• Where possible, a minimal Rabbit-in-a-Hat reproduction.