Altair Monarch Troubleshooting Guide

About Altair Monarch

Altair Monarch is a self-service data preparation tool that extracts structured data from unstructured sources — PDF reports, text files, HTML pages, and similar formats — and transforms it for downstream analysis. Part of the Altair RapidMiner platform, it is used widely across manufacturing, finance, and logistics workflows where the source data cannot be changed. The three categories above account for the majority of Monarch support escalations; each is covered in detail below.

Issue category 1: COM Auto setup

What is COM Auto, and why does it break? Monarch's Component Object Model (COM) automation interface lets external applications — scripts, task schedulers, and third-party tools — drive Monarch programmatically. The COM component must be registered in the Windows registry before it can be called. That registration is installation-dependent and can break silently when Monarch is upgraded, the install path changes, a Windows update modifies permissions, or the component is registered under a different user account. These failures usually surface as cryptic runtime errors in the calling script rather than as errors in Monarch itself.

1.1 — “Cannot create ActiveX component” or “Class not registered” error

Cause: the COM component is not registered, or is registered incorrectly. This error appears in VBScript, PowerShell, or any external process that calls Monarch via COM. The Monarch COM server is invisible to Windows because it was never registered, was deregistered by a version upgrade, or was registered under a different system context.

Resolution steps:

1. Open Command Prompt as Administrator. Right-click Command Prompt and choose Run as administrator. This is required — running without elevation will fail silently.
2. Navigate to the Monarch install directory. Default path: cd "C:\Program Files\Altair\Monarch\<version>"
3. Re-register the COM component: regsvr32 MonarchEngine.dll
4. Confirm the success dialog. Windows will display “DllRegisterServer in MonarchEngine.dll succeeded.” If it fails, the file path is wrong or the account lacks permissions.
5. Restart the calling application or service and re-run the automation.

If Monarch is installed in a non-default path (for example, a network drive or a custom directory), substitute the actual install path in step 2. Check Add/Remove Programs if the path is unknown.

1.2 — COM automation works manually but fails under Task Scheduler or a service account

Cause: COM is registered for one user context but called from another. Windows COM registration is per-user by default unless it is explicitly registered system-wide. If Monarch was registered by an administrator account but is called by a service account or scheduled task running as a different user, the registration is invisible to that process.

Resolution steps:

1. Identify the account running the scheduled task or service. In Task Scheduler: right-click the task → Properties → General tab → the “Run as” field.
2. Log in as that service account and re-register the COM component from that account's context.
3. Alternatively, register the COM component system-wide using the /s flag to suppress dialogs, from an elevated prompt: regsvr32 /s MonarchEngine.dll
4. Verify the task runs successfully by triggering it manually from Task Scheduler.

Do not register the component as SYSTEM unless your environment requires it. Use the least-privileged account that has read/write access to the Monarch temp and output directories.

1.3 — COM registration succeeds but automation still fails after a Monarch upgrade

Cause: the old version's COM registration persists while the new DLL is never registered. The calling application finds the old registration entry, which now points to a DLL that has moved or no longer exists, producing a “file not found” or “invalid class” error.

Resolution steps:

1. Unregister the old COM entry: regsvr32 /u "C:\Program Files\Altair\Monarch\<old_version>\MonarchEngine.dll"
2. Register the new version: regsvr32 "C:\Program Files\Altair\Monarch\<new_version>\MonarchEngine.dll"
3. Confirm both operations succeed before testing automation.

Check the ProgID in your calling script. Some scripts reference a version-specific ProgID (for example, DataLens.Application.16) rather than the version-independent one (DataLens.Application). If you pin to a version-specific ProgID, update your script after each upgrade.

Issue category 2: Version migration

Why Monarch upgrades break existing models. Monarch model files (.xmod in Monarch 15 and later, .dmod in earlier versions) encode trap definitions, field mappings, filters, and export configurations. Across major versions, Altair occasionally changes the internal XML schema, renames configuration keys, or deprecates trap types. A model built in an older version may open in a newer version yet produce incorrect output, fail silently, or require re-mapping of fields. The most common migration pain points are trap types that no longer exist in the new version, field expressions that use renamed or removed functions, and export configurations tied to ODBC drivers or file paths that have changed.

2.1 — Model opens after an upgrade but produces no output or the wrong records

Cause: trap definitions were silently invalidated by a version schema change.

Resolution steps:

1. Open the model in Monarch's Report Design view and visually verify that each trap (header, append, footer, detail) is still defined and active. Inactive traps appear without the green triangle indicator.
2. Run the model against a known input file and check the Sample window. If the record count is 0 or differs significantly from the previous version, the traps are not matching.
3. Re-define the affected traps from scratch against the same input file. Do not copy trap definitions from the old model — this can carry the broken schema forward.
4. Re-validate all calculated fields. Open each calculated field and re-run it against a sample. Functions such as @Left, @Trim, and @DateToStr occasionally have parameter changes between major versions.
5. Save the model under a new name for the new version. Retain the original for rollback in case you need to reproduce output from the old version.

2.2 — A model worked in Monarch Classic but fails in Monarch Complete, or vice versa

Cause: a product-edition mismatch — features available in Complete are not available in Classic. Monarch Classic and Monarch Complete are different editions. Complete includes advanced joins, multi-table models, and additional export connectors. A model built using Complete features — particularly multi-table joins or Process Designer logic — will open in Classic but silently drop those features.

Resolution steps:

1. Identify which edition your license covers. In Monarch, go to Help → About and confirm whether you are running Classic or Complete.
2. If moving from Complete to Classic, rebuild the model using only Classic-compatible features. Multi-table joins must be replaced with single-table extraction logic or pre-joined input files.
3. If moving from Classic to Complete, the model should be compatible. However, re-test all export paths, as Complete handles ODBC and database connections differently.

Contact TrueInsight if you are unsure which edition your license includes. The edition is confirmed in your Altair One account or your license file.

2.3 — Export fails after an upgrade; ODBC driver or file path not found

Cause: the export destination or driver reference is no longer valid in the new install.

Resolution steps:

1. Open the model's Export section and review each export destination. Check for hardcoded paths (for example, C:\Users\<old_user>\...) that may no longer exist in the new environment.
2. Verify ODBC data sources. Open the ODBC Data Source Administrator (odbcad32.exe) and confirm that any System DSN your model references still exists and points to the correct database server.
3. Re-create missing ODBC DSNs under the same name with the correct connection parameters. Monarch stores the DSN name, not the full connection string, so the name must match exactly.
4. Update hardcoded paths in the model to use UNC paths or environment variables where possible, to reduce fragility on future upgrades.

Issue category 3: Corrupted output recovery

When Monarch produces wrong data: causes and approach. Corrupted output means the model runs without error but produces records that are incorrect, incomplete, misaligned, or blank. This is distinct from a process failure: the model appears to work — an output file is created and the record count looks plausible — but the data is wrong. Root causes fall into three groups: the input file format has changed since the model was built, template traps are matching unintended content, or field expressions are mishandling data types, delimiters, or locale-specific characters.

3.1 — Output fields are blank, or all records return the same value

Cause: a trap or field definition no longer matches the input file format.

Resolution steps:

1. Open the report in Monarch's Report view alongside the model. Visually compare the trap anchors (the underlined text Monarch uses to identify record boundaries) against the current report. If the source format changed — column widths shifted, headers added, encoding changed — the anchors will no longer sit at the correct positions.
2. Re-anchor the traps against the current report format. Delete and redefine the detail trap first, then the header and footer traps.
3. Check field column positions. In the field editor, verify that each field's start and end column positions still correspond to the correct data columns. Even a one-character shift in the source format will misalign every subsequent field.
4. Run the model and verify the Sample window shows correct data before exporting.

3.2 — Numeric fields export as text, or contain extra characters

Cause: a field-type mismatch, or a locale decimal/thousands-separator conflict.

Resolution steps:

1. Open the field definition in Monarch's field editor and confirm the field type is set to Numeric, not Character. A Character field will export numbers as text strings.
2. Check the decimal and thousands separator settings. If the source file uses European formatting (1.000,00 rather than 1,000.00), Monarch's default locale settings will misparse the value. Go to Options → Application Options → Locale and verify the separator settings match the source file's origin locale.
3. Use the @Val() function in a calculated field to force conversion of a character representation of a number to a numeric type if the field type alone is insufficient.
4. Strip non-numeric characters from the extracted field before exporting, using @ReplaceStr or a regular expression to remove currency symbols, spaces, or stray characters the trap captured alongside the value.

3.3 — Output has the correct record count but rows are misaligned, with data in the wrong columns

Cause: fixed-width field boundaries no longer match the source layout.

Resolution steps:

1. Open the report in Report view and display column rulers (View → Ruler). Compare the ruler positions against the current field definitions.
2. Look for a layout change in the source. Common triggers: the generating system was updated, a new column was added upstream, or the output font or page width changed (which affects fixed-width PDF extraction).
3. Use Monarch's automatic template wizard on a fresh copy of the current report to see what field boundaries it detects, then compare against the existing model to identify the shift.
4. Update each field's column positions to match the current layout. Start with the leftmost field and work right — a single position correction may cascade to fix every downstream field.
5. Test with multiple sample files from different dates if possible, to confirm the layout is consistently correct and not variable.

If the source is a PDF, remember that PDFs have no fixed column grid. Monarch estimates column positions from glyph positions in the PDF, so a change in the PDF-generating application (a different printer driver or PDF export setting, for example) can shift all column positions even when the visible content looks identical.

3.4 — Output is empty after a source-system change, though the model ran successfully

Cause: a header trap anchor text changed in the source, so the model no longer finds any records. If the source system changed its header format even slightly — for instance, relabeling “Invoice Date” as “Inv. Date” — Monarch's header trap will no longer match. Without a matching header trap, Monarch cannot find the detail records, so the output is empty. No error is generated because the model is technically valid; it simply found zero matching records.

Resolution steps:

1. Open the report in Report view and manually locate the header record. Compare it character by character against the header trap anchor definition in the model.
2. Update the header trap anchor to match the current header text exactly, including spacing and capitalization.
3. Make header traps more resilient by anchoring on a shorter, more stable substring that is unlikely to change (for example, a column position rather than a full label string).
4. Re-run the model and verify the Sample window shows the expected record count before exporting.