Ssis-998 -

SQL Server Integration Services (SSIS) is a powerful ETL platform, but like any complex engine it throws cryptic error codes when something goes wrong. One of the most frequently encountered (and sometimes confusing) codes is SSIS‑998 . Below is a deep‑dive guide that explains the error, walks you through typical root‑causes, and provides a step‑by‑step troubleshooting/playbook you can use in any SSIS project. 1. Quick Definition | Item | Description | |------|-------------| | Error Code | SSIS‑998 | | Message (typical) | The metadata of the external column "ColumnName" does not match the metadata of the column in the data flow component. | | Severity | Fatal – the package execution stops unless the error is caught and handled. | | Component Types | Appears most often in Data Flow components (OLE DB Source/Destination, Flat File Source/Destination, ADO.NET Source, CDC components, etc.), but can also surface in Control Flow when a task tries to read a table/column that no longer exists. | | Underlying SQL Server Error | Often maps to SQL Server error 998 – “Invalid column name” or SQL Server error 207 – “Invalid column name” . | Bottom line: SSIS‑998 tells you that the metadata that SSIS thinks a column has (name, data type, length, precision, etc.) no longer matches the actual metadata in the source or destination . 2. Typical Scenarios That Trigger SSIS‑998 | # | Scenario | Why the Metadata Mismatch Occurs | |---|----------|-----------------------------------| | 1 | Schema change in source database (column added, renamed, data type altered, dropped). | SSIS package was built against the previous schema; the runtime component still expects the old definition. | | 2 | Flat‑file layout change (new delimiter, extra column, column order changed). | The Flat File Connection Manager caches column definitions when the package is opened; a change on disk isn’t automatically refreshed. | | 3 | Dynamic SQL / Variable‑driven queries where the SELECT list changes based on parameters. | The metadata is inferred at design time; at runtime the result set can be different. | | 4 | Data type promotion / precision loss (e.g., a decimal(18,2) column becomes decimal(19,4) ). | SSIS component stores the original precision/scale and will reject the new definition. | | 5 | Using a staging table that is truncated/re‑created between runs (e.g., CREATE TABLE #tmp … ). | The temporary object is recreated with a different schema, but the component’s metadata is still the original. | | 6 | CDC (Change Data Capture) components after a CDC capture instance is re‑initialized. | CDC metadata (LSN, column list) may be refreshed, causing a mismatch with the CDC Source component. | | 7 | Package versioning – you open a package in an older SSIS Designer version that cannot interpret newer data type definitions. | The older runtime cannot map new types (e.g., datetime2(7) ) correctly. | 3. How to Diagnose the Problem | Step | Action | What to Look For | |------|--------|-------------------| | 3.1 | Enable detailed logging (SSIS log provider for Text/SQL Server). | Look for a line that starts with Error: 0xC0047064 (or similar) and contains SSIS‑998 . The message will usually contain the component name and the offending column. | | 3.2 | Open the Data Flow Designer and locate the component mentioned in the log. | Hover over red error icons → you’ll see the same “metadata does not match” text. | | 3.3 | View the component’s metadata (right‑click → Show Advanced Editor → Input and Output Properties ). | Compare the Data Type , Length , Precision , Scale , and Column Name with the source/destination definition. | | 3.4 | Run a “Validate” on the data flow (right‑click the Data Flow → Validate ). | Validation will fail with the same error, confirming the mismatch before the package even starts. | | 3.5 | Query the source schema directly (e.g., SELECT TOP 0 * FROM dbo.MyTable ). | Verify column names, order, and data types against what SSIS thinks they are. | | 3.6 | Check for dynamic SQL – open any variables/expressions that build a SELECT statement. | Ensure the SELECT list is static or that you have used the “ValidateExternalMetadata = False” property where appropriate. | | 3.7 | Inspect the connection manager (right‑click → Properties ). | For flat files, check Columns , Data Type , Format , Header rows , etc. For OLE DB, check AlwaysUseDefaultCodePage and RetainSameConnection . | 4. Step‑by‑Step Fixes Below are the most common fixes, ordered from quick “reset” tricks to more robust, future‑proof solutions . 4.1 Quick “Refresh” Fixes | Fix | When to Use | How to Apply | |-----|-------------|--------------| | Refresh the connection manager | You made a schema change and the package was not reopened. | Close the package, reopen it, then click Refresh on the OLE DB/Flat File connection manager (or right‑click → Properties → ValidateExternalMetadata = True ). | | Delete and re‑add the column | Only one column is mismatched. | In the component’s Input and Output tab, delete the offending column and click Add Column → map it again. | | Set ValidateExternalMetadata = False | The source schema is truly dynamic (e.g., a stored procedure that returns varying columns). | On the problematic source component, set the property ValidateExternalMetadata to False . This tells SSIS to skip design‑time validation and rely on runtime. Use with caution—make sure downstream components can handle any shape. | | Re‑create the component | The component’s internal metadata cache is corrupted. | Delete the source/destination component and drag a fresh one onto the canvas, re‑configure it. | 4.2 Robust, Long‑Term Fixes | Fix | Why It Helps | Implementation Tips | |-----|--------------|----------------------| | Add a “Schema Refresh” step (Execute SQL Task → sp_refreshview or sp_refreshsqlmodule ). | Guarantees the metadata in the database is up‑to‑date before SSIS reads it. | Place the task just before the Data Flow, commit the transaction only after the refresh succeeds. | | Use a Derived Column or Data Conversion component to explicitly cast data types. | Removes ambiguity when source column data type changes (e.g., int → bigint ). | Set the output data type to the “most permissive” version you expect, then downstream components can safely accept it. | | Implement a Package Configuration (or Project Parameter) to store the schema version . | Allows you to version‑control the expected column list and raise a custom error if the source deviates. | In the OnPreExecute event handler, query the source’s INFORMATION_SCHEMA.COLUMNS and compare with a JSON parameter. | | Leverage the “ OLE DB Destination – Fast Load” with Table or View – Name of the Table instead of Table or View – Fast Load Options . | Fast Load uses bulk‑copy semantics that are more tolerant of column order changes when you map columns by name (not position). | In the Destination editor → Mappings tab → ensure Map by name is selected. | | Add a “Staging Table” with a stable schema and load from it into the final destination. | Isolates downstream packages from upstream schema changes. | The upstream process (or a separate package) is responsible for adjusting the staging schema; downstream packages only ever see the same columns. | | Automate metadata validation with a script task . | Detects mismatches early in CI/CD pipelines. | Write a C# script that reads IDTSComponentMetaData100 objects from the package and compares them to the live source schema (using SqlConnection.GetSchema ). Fail the build if any drift is found. | 5. Real‑World Example 5.1 Problem Statement An SSIS package loads daily sales data from dbo.Sales_Stg (a staging table) into dbo.Sales . After a database upgrade, the column SaleAmount was altered from money to decimal(18,4) . When the package runs, it fails with:

SQL Server Integration Services (SSIS) is a powerful ETL platform, but like any complex engine it throws cryptic error codes when something goes wrong. One of the most frequently encountered (and sometimes confusing) codes is SSIS‑998 . Below is a deep‑dive guide that explains the error, walks you through typical root‑causes, and provides a step‑by‑step troubleshooting/playbook you can use in any SSIS project. 1. Quick Definition | Item | Description | |------|-------------| | Error Code | SSIS‑998 | | Message (typical) | The metadata of the external column "ColumnName" does not match the metadata of the column in the data flow component. | | Severity | Fatal – the package execution stops unless the error is caught and handled. | | Component Types | Appears most often in Data Flow components (OLE DB Source/Destination, Flat File Source/Destination, ADO.NET Source, CDC components, etc.), but can also surface in Control Flow when a task tries to read a table/column that no longer exists. | | Underlying SQL Server Error | Often maps to SQL Server error 998 – “Invalid column name” or SQL Server error 207 – “Invalid column name” . | Bottom line: SSIS‑998 tells you that the metadata that SSIS thinks a column has (name, data type, length, precision, etc.) no longer matches the actual metadata in the source or destination . 2. Typical Scenarios That Trigger SSIS‑998 | # | Scenario | Why the Metadata Mismatch Occurs | |---|----------|-----------------------------------| | 1 | Schema change in source database (column added, renamed, data type altered, dropped). | SSIS package was built against the previous schema; the runtime component still expects the old definition. | | 2 | Flat‑file layout change (new delimiter, extra column, column order changed). | The Flat File Connection Manager caches column definitions when the package is opened; a change on disk isn’t automatically refreshed. | | 3 | Dynamic SQL / Variable‑driven queries where the SELECT list changes based on parameters. | The metadata is inferred at design time; at runtime the result set can be different. | | 4 | Data type promotion / precision loss (e.g., a decimal(18,2) column becomes decimal(19,4) ). | SSIS component stores the original precision/scale and will reject the new definition. | | 5 | Using a staging table that is truncated/re‑created between runs (e.g., CREATE TABLE #tmp … ). | The temporary object is recreated with a different schema, but the component’s metadata is still the original. | | 6 | CDC (Change Data Capture) components after a CDC capture instance is re‑initialized. | CDC metadata (LSN, column list) may be refreshed, causing a mismatch with the CDC Source component. | | 7 | Package versioning – you open a package in an older SSIS Designer version that cannot interpret newer data type definitions. | The older runtime cannot map new types (e.g., datetime2(7) ) correctly. | 3. How to Diagnose the Problem | Step | Action | What to Look For | |------|--------|-------------------| | 3.1 | Enable detailed logging (SSIS log provider for Text/SQL Server). | Look for a line that starts with Error: 0xC0047064 (or similar) and contains SSIS‑998 . The message will usually contain the component name and the offending column. | | 3.2 | Open the Data Flow Designer and locate the component mentioned in the log. | Hover over red error icons → you’ll see the same “metadata does not match” text. | | 3.3 | View the component’s metadata (right‑click → Show Advanced Editor → Input and Output Properties ). | Compare the Data Type , Length , Precision , Scale , and Column Name with the source/destination definition. | | 3.4 | Run a “Validate” on the data flow (right‑click the Data Flow → Validate ). | Validation will fail with the same error, confirming the mismatch before the package even starts. | | 3.5 | Query the source schema directly (e.g., SELECT TOP 0 * FROM dbo.MyTable ). | Verify column names, order, and data types against what SSIS thinks they are. | | 3.6 | Check for dynamic SQL – open any variables/expressions that build a SELECT statement. | Ensure the SELECT list is static or that you have used the “ValidateExternalMetadata = False” property where appropriate. | | 3.7 | Inspect the connection manager (right‑click → Properties ). | For flat files, check Columns , Data Type , Format , Header rows , etc. For OLE DB, check AlwaysUseDefaultCodePage and RetainSameConnection . | 4. Step‑by‑Step Fixes Below are the most common fixes, ordered from quick “reset” tricks to more robust, future‑proof solutions . 4.1 Quick “Refresh” Fixes | Fix | When to Use | How to Apply | |-----|-------------|--------------| | Refresh the connection manager | You made a schema change and the package was not reopened. | Close the package, reopen it, then click Refresh on the OLE DB/Flat File connection manager (or right‑click → Properties → ValidateExternalMetadata = True ). | | Delete and re‑add the column | Only one column is mismatched. | In the component’s Input and Output tab, delete the offending column and click Add Column → map it again. | | Set ValidateExternalMetadata = False | The source schema is truly dynamic (e.g., a stored procedure that returns varying columns). | On the problematic source component, set the property ValidateExternalMetadata to False . This tells SSIS to skip design‑time validation and rely on runtime. Use with caution—make sure downstream components can handle any shape. | | Re‑create the component | The component’s internal metadata cache is corrupted. | Delete the source/destination component and drag a fresh one onto the canvas, re‑configure it. | 4.2 Robust, Long‑Term Fixes | Fix | Why It Helps | Implementation Tips | |-----|--------------|----------------------| | Add a “Schema Refresh” step (Execute SQL Task → sp_refreshview or sp_refreshsqlmodule ). | Guarantees the metadata in the database is up‑to‑date before SSIS reads it. | Place the task just before the Data Flow, commit the transaction only after the refresh succeeds. | | Use a Derived Column or Data Conversion component to explicitly cast data types. | Removes ambiguity when source column data type changes (e.g., int → bigint ). | Set the output data type to the “most permissive” version you expect, then downstream components can safely accept it. | | Implement a Package Configuration (or Project Parameter) to store the schema version . | Allows you to version‑control the expected column list and raise a custom error if the source deviates. | In the OnPreExecute event handler, query the source’s INFORMATION_SCHEMA.COLUMNS and compare with a JSON parameter. | | Leverage the “ OLE DB Destination – Fast Load” with Table or View – Name of the Table instead of Table or View – Fast Load Options . | Fast Load uses bulk‑copy semantics that are more tolerant of column order changes when you map columns by name (not position). | In the Destination editor → Mappings tab → ensure Map by name is selected. | | Add a “Staging Table” with a stable schema and load from it into the final destination. | Isolates downstream packages from upstream schema changes. | The upstream process (or a separate package) is responsible for adjusting the staging schema; downstream packages only ever see the same columns. | | Automate metadata validation with a script task . | Detects mismatches early in CI/CD pipelines. | Write a C# script that reads IDTSComponentMetaData100 objects from the package and compares them to the live source schema (using SqlConnection.GetSchema ). Fail the build if any drift is found. | 5. Real‑World Example 5.1 Problem Statement An SSIS package loads daily sales data from dbo.Sales_Stg (a staging table) into dbo.Sales . After a database upgrade, the column SaleAmount was altered from money to decimal(18,4) . When the package runs, it fails with: