Conversion issues#
Purpose#
An Issue is a structured diagnostic from a conversion.
Warnings, errors, and failures are all Issue objects.
The issue location in a Result defines its effect:
A warning does not change the result status. It can describe recovery or uncertainty in the output.
An error identifies requested work that is incomplete.
A failure identifies the reason that conversion stopped.
Investigate a reported element issue#
A diagnostic identifies the conversion problem and, when available, the affected object and the consequence for the output. It does not necessarily establish the underlying cause or a specific repair. For example, a geometry extraction issue can identify an element whose mesh was omitted without establishing why tessellation failed.
When the subject identifies a DGN element, use that identity to locate and inspect the element in the native CAD application. Element handles in these diagnostics are reported in decimal. Review the source element and determine whether a change is appropriate there. If you make a change, save an updated copy, rerun conversion, and compare the diagnostics and output. This is an investigation starting point, not a guaranteed fix or evidence that the source element is defective. An omitted element may have no corresponding prim in the USD output.
Not every subject is an element: it can identify a file, parameter, database object, or USD target. Use the code descriptions below to interpret it. Review the conversion logs alongside the result; enabling verboseLogging may provide additional context, but does not guarantee a root cause or repair instruction. See Conversion results for reporting coverage and the extension overview for how these diagnostics reach extension callers.
Interpret an issue#
Each reported issue has three values:
codeis a stable, machine-readableIssueCodevalue.messageis a human-readable description.subjectidentifies the object associated with the issue.
Use code for program logic.
Use formatIssue(issue) for logs and user-facing diagnostic output that needs the object’s identity.
Use message when the subject is already displayed separately.
Do not match message text in program logic.
The meaning of subject depends on the code.
An empty subject means that no subject is available or applicable.
formatIssue() returns the message prefixed by the quoted subject and a code-specific label when available.
For example, an invalid parameter can display as Parameter 'curveSamplePoints': The value must be at least 2.
The message describes the observed condition and any known cause, recovery, or consequence. It does not necessarily identify the underlying cause.
It does not routinely repeat the subject.
It can identify other objects needed to explain the issue.
When the subject is empty, formatting returns the message alone.
Formatting an empty Issue returns an empty string.
Formatting does not change the issue or emit a log entry.
Quotes, backslashes, and control characters in the subject are escaped for display.
subject retains the original identity.
Display text and labels are not stable identifiers. Use the original fields for program logic.
Use hasIssue() to check whether an Issue represents a reported diagnostic.
getFailure() returns an empty issue when the result did not fail.
Create an issue#
Issue() represents no issue: its code is eNone, its strings are empty, and hasIssue() returns false.
In Python, this empty value is an Issue object, not None.
The other constructors require a reportable code and a non-empty message.
They reject eNone, eMax, unsupported codes, and empty messages.
These arguments raise std::invalid_argument in C++ or ValueError in Python.
The subject is optional and can be empty.
C++ exposes code, message, and subject as mutable fields.
In Python, code and message are read-only, while subject is writable.
Set the subject before you record the issue in a result.
Issue construction does not emit a diagnostic.
Issue codes#
Each code defines its meaning, permitted result role, and subject.
These definitions are part of the public API contract.
Code-specific roles describe how the converter reports an issue.
The Result mutation methods do not validate these roles or prevent duplicate issues.
Code that records an issue must select its documented role.
eNone#
Meaning: No issue occurred.
Reported as: This code is not a warning, error, or failure.
Subject: Empty.
The default Issue value uses this code.
eUndefined#
Meaning: An issue occurred, but the converter cannot assign a more specific code.
Reported as: A warning, error, or failure, according to the effect on conversion.
Subject: The associated object’s identity when available, otherwise empty. This code does not define a subject type, so formatting uses no subject label.
Use the message to understand an undefined issue.
eInvalidInputPath#
Meaning: The input path does not identify an available DGN file.
Reported as: A failure.
Subject: The exact input path supplied by the caller. The subject can itself be empty.
eInvalidOutputPath#
Meaning: The output path does not identify a writable destination in a supported USD format.
Reported as: A failure.
Subject: The exact output path supplied by the caller. The subject can itself be empty.
eInvalidOutputLayer#
Meaning: The output layer cannot store converted USD data.
Reported as: A failure.
Subject: The output layer identifier, when available. The subject is empty for a null layer.
eInvalidParameter#
Meaning: A conversion parameter contains a value that the converter cannot use safely.
Reported as: An error that supports an eInvalidParameters failure.
Subject: The canonical parameter name.
Each invalid parameter has a separate error. This structure lets callers identify all invalid parameters in one conversion attempt.
eIgnoredParameter#
Meaning: Another parameter disables a supplied, non-default parameter value.
Reported as: A warning.
Subject: The canonical parameter name.
The ignored value has no effect on conversion.
eDefaultedParameter#
Meaning: The converter discards a parameter value and uses the documented default.
Reported as: A warning.
Subject: The canonical parameter name.
eModifiedParameter#
Meaning: The converter changes or partially uses a parameter value.
Reported as: A warning.
Subject: The canonical parameter name.
For example, the converter can retain valid list entries and remove malformed entries.
eInvalidParameters#
Meaning: One or more conversion parameters prevent conversion.
Reported as: A failure.
Subject: Empty because this issue represents multiple parameters.
The message lists the distinct parameter names when they are available.
The errors collection contains one eInvalidParameter for each invalid parameter.
eOdaActivationFailed#
Meaning: The ODA runtime license could not be activated.
Reported as: A failure.
Subject: Empty.
An invalid license can also surface during initialization, module loading, or file reading. The subject remains empty because the failure concerns the shared ODA runtime.
eOdaInitializationFailed#
Meaning: The ODA runtime could not be initialized.
Reported as: A failure.
Subject: Empty.
eOdaModuleLoadFailed#
Meaning: A required ODA module could not be loaded.
Reported as: A failure.
Subject: The name of the ODA module whose load failed. The subject is empty when the failure is not associated with a specific module.
eInvalidInputFile#
Meaning: The input file is not a valid DGN drawing or its contents are corrupt.
Reported as: A failure.
Subject: The exact input path supplied by the caller.
eUnsupportedInputFileVersion#
Meaning: The input file uses a DGN version that the configured ODA runtime cannot read.
Reported as: A failure.
Subject: The exact input path supplied by the caller.
eInputFileAccessFailed#
Meaning: The input file could not be opened for reading because of a file-system, access, lock, or sharing error.
Reported as: A failure.
Subject: The exact input path supplied by the caller.
eInputFilePasswordError#
Meaning: The input file could not be opened because of password protection.
Reported as: A failure.
Subject: The exact input path supplied by the caller.
eInputFileReadFailed#
Meaning: The input file could not be read, but the failure does not have a more specific issue code.
Reported as: A failure.
Subject: The exact input path supplied by the caller.
eInputFileEncrypted#
Meaning: ODA confirmed that the input DGN is encrypted after it could not read the file.
Reported as: A failure.
Subject: The exact input path supplied by the caller.
Request an unencrypted DGN export from the file’s author and retry conversion. This code does not establish that the file requires a password or that supplying one would permit conversion. Specific read failures, such as invalid file contents, access failures, and password errors, keep their existing codes. If the encryption check cannot determine the flag, the original read diagnostic is retained.
eColorTableRecoveryFailed#
Meaning: The malformed DGN extended color table could not be recovered during input file reading. Some source colors may therefore be unavailable in the converted output.
Reported as: An error. Conversion continues and the result is incomplete unless a later failure stops conversion.
Subject: The exact input path supplied by the caller.
The converter continues with the original file data when recovery fails. If it cannot reload that data, conversion stops and retains the recovery error alongside the read failure. A successful repair does not produce this issue.
eStageCreationFailed#
Meaning: A USD stage could not be created for conversion, either in memory for file output or by opening a supplied output layer.
Reported as: A failure. Conversion stops before reading the DGN file or authoring converted content.
Subject: The requested output path for in-memory stage creation, or the supplied output layer identifier when opening a stage.
Null or non-editable output layers are rejected earlier with eInvalidOutputLayer.
Failures to author data to an existing stage use eStageAuthoringFailed.
eInvalidModelUnits#
Meaning: A selected Model has a non-positive or non-finite working-unit conversion. The converter ignores the invalid units and uses centimeters. Conversion continues, but the content’s scale may be incorrect.
Reported as: A warning.
Subject: The DGN Model name.
eDefaultedStageUnits#
Meaning: No selected Model supplies valid working units, so the Stage uses centimeters. The message distinguishes an empty Model selection from Models with unusable units.
Reported as: A warning.
Subject: Empty because this issue concerns the selected Models as a whole.
Invalid units in individual Models also produce eInvalidModelUnits warnings during hierarchy conversion,
including Models without convertible Elements.
eInputFileReadIncomplete#
Meaning: Some input data could not be read, but the loaded database remains available for conversion.
Reported as: An error. Conversion continues and the result is incomplete unless a later failure stops conversion.
Subject: The exact input path supplied by the caller.
This code is part of the public API, but the converter does not currently emit it.
eDatabaseReadFailed#
Meaning: An object in the loaded DGN database could not be read.
Reported as: A failure when essential data is unavailable, or an error when conversion can continue with incomplete output.
Subject: The name or type of the database object, such as SharedCellDefinitionTable or LevelTable.
For an invalid or unreadable Element, the subject is its decimal DGN Element handle; the message identifies the affected or parent Prim when its path is known.
For an unavailable Shared Cell Definition, the subject is the referring Prim path.
An unavailable Shared Cell Definition Table or table iterator reports a failure and stops conversion. An available but empty table does not produce an issue.
Null and empty child Element iterators are treated as having no Elements and do not produce an issue.
Invalid or unreadable Model and Shared Cell Definition entries report errors when their Prim hierarchies are omitted. Unreadable Elements, unavailable Shared Cell Definitions, and failed text extraction report errors. Conversion continues with the remaining content.
When effective Level filtering is enabled, an unavailable Level Table reports an error and disables filtering.
Depending on the requested filter style, the Stage can contain extra Prims or Prims that remain visible or active.
An empty Level Table or a filter that matches no Levels does not produce this issue.
When the effective levelFilterStyle is eNone, an unavailable Level Table does not produce this issue.
eGeometryExtractionFailed#
Meaning: An Element’s requested geometry could not be extracted completely.
Reported as: An error. Conversion continues with the remaining geometry.
Subject: The source Element’s decimal DGN handle.
The message describes the extraction problem and the omitted geometry. A successful fallback does not report the failed extraction attempt. Geometry excluded by conversion settings does not produce this issue.
Code labels#
getIssueCodeLabel() returns a brief label for an IssueCode value.
The eMax boundary and unrecognized values use the Unsupported label.
Python also returns the label when code calls str() on an issue code.
Labels are for logs and diagnostic output. They are not stable API identifiers.
Stable numeric values#
Issue-code numeric values are stable public API values. Do not reuse or renumber them.
Code |
Value |
|---|---|
|
0 |
|
1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
|
9 |
|
10 |
|
11 |
|
12 |
|
13 |
|
14 |
|
15 |
|
16 |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 |
|
22 |
|
23 |
|
24 |
|
25 |
|
26 |
eMax is the exclusive upper boundary for declared issue codes.
It is not a reportable issue code.