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 below account for the majority of Monarch support escalations.

Issue category 1: COM Auto setup

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.

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.

• Open Command Prompt as Administrator. Right-click Command Prompt and choose Run as administrator.
• Navigate to the Monarch install directory: cd "C:\Program Files\Altair\Monarch<version>"
• Re-register the COM component: regsvr32 MonarchEngine.dll
• Confirm the success dialog: “DllRegisterServer in MonarchEngine.dll succeeded.”
• Restart the calling application or service and re-run the automation.
• If Monarch is installed in a non-default path, substitute the actual install path.
• Restart the calling application or service and re-run the automation.

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.

• Identify the account running the scheduled task or service.
• In Task Scheduler, right-click the task, open Properties, and check the General tab.
• Log in as that service account and re-register the COM component from that account's context.
• Alternatively, register the COM component system-wide from an elevated prompt: regsvr32 /s MonarchEngine.dll
• Verify the task runs successfully by triggering it manually from Task Scheduler.
• Do not register the component as SYSTEM unless your environment requires it.

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.

• Unregister the old COM entry: regsvr32 /u "C:\Program Files\Altair\Monarch<old_version>\MonarchEngine.dll"
• Register the new version: regsvr32 "C:\Program Files\Altair\Monarch<new_version>\MonarchEngine.dll"
• Confirm both operations succeed before testing automation.
• Check the ProgID in your calling script.
• If the script uses a version-specific ProgID, update it after the upgrade.

Issue category 2: Version migration

Monarch model files encode trap definitions, field mappings, filters, and export configurations. Across major versions, Altair may change the internal XML schema, rename configuration keys, or deprecate 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.

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.

• Open the model in Monarch's Report Design view.
• Verify that each trap — header, append, footer, and detail — is still defined and active.
• 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.
• Re-define the affected traps from scratch against the same input file.
• Re-validate all calculated fields.
• Save the model under a new name for the new version and retain the original for rollback.

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

Cause: a product-edition mismatch. Features available in Monarch Complete are not available in Monarch Classic. Complete includes advanced joins, multi-table models, and additional export connectors. A model built using Complete features may open in Classic but silently drop those features.

• Confirm the edition in Help → About.
• If moving from Complete to Classic, rebuild the model using only Classic-compatible features.
• Replace multi-table joins with single-table extraction logic or pre-joined input files.
• If moving from Classic to Complete, re-test all export paths.
• Contact TrueInsight if you are unsure which edition your license includes.

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.

• Open the model's Export section and review each export destination.
• Check for hardcoded paths that may no longer exist in the new environment.
• Open the ODBC Data Source Administrator and confirm that any System DSN still exists.
• Re-create missing ODBC DSNs under the same name with the correct connection parameters.
• Update hardcoded paths to use UNC paths or environment variables where possible.

Issue category 3: Corrupted output recovery

Corrupted output means the model runs without error but produces records that are incorrect, incomplete, misaligned, or blank. This is different from a process failure: the model may create an output file and show a plausible record count, but the data is wrong. Common causes include input format changes, traps matching unintended content, or field expressions 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.

• Open the report in Monarch's Report view alongside the model.
• Compare the trap anchors against the current report.
• Check whether column widths, headers, or encoding changed.
• Re-anchor the traps against the current report format.
• Delete and redefine the detail trap first, then the header and footer traps.
• Check field column positions.
• Run the model and verify the Sample window 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.

• Open the field definition in Monarch's field editor.
• Confirm the field type is Numeric, not Character.
• Check the decimal and thousands separator settings.
• Go to Options → Application Options → Locale and verify that the separators match the source file.
• Use @Val() in a calculated field to force conversion to numeric.
• Strip non-numeric characters using @ReplaceStr or a regular expression.

3.3 — Output has the correct record count but rows are misaligned

Cause: fixed-width field boundaries no longer match the source layout. For PDFs, Monarch estimates column positions from glyph positions, so a change in the PDF-generating application can shift columns even when the visible content looks identical.

• Open the report in Report view and display column rulers.
• Compare the ruler positions against the current field definitions.
• Look for a source layout change, such as a system update, new column, font change, or page-width change.
• Run Monarch's automatic template wizard on a fresh copy of the current report.
• Compare the detected boundaries against the existing model.
• Update each field's column positions from left to right.
• Test with multiple sample files from different dates.

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. For example, if “Invoice Date” changed to “Inv. Date”, Monarch's header trap may no longer match. No error appears because the model is technically valid; it simply matched zero records.

• 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.
• Update the header trap anchor to match the current header text exactly.
• Check spacing and capitalization.
• Make header traps more resilient by using a shorter, stable substring or a column position.
• Re-run the model and verify the Sample window shows the expected record count.