Troubleshooting
When you work with the Import API v2, you might encounter situations where import operations fail. Some of the potential reasons are:
- The content of the input file has an invalid structure.
- One of the mandatory parameters for a command is missing.
- The import resource defined by a command violates a business constraint.
To help you identify the cause of failure, the following tables explain the most common errors. The error codes are logged in Collibra Console.
Generic command errors
| Error code (visible in dgc.log) | Structure of error message | Reason |
|---|---|---|
| importCommandIdentifierAmbiguous | There are either too many or too few parameters to identify the {0}. As a general rule, use the resource ID as an identifier or the resource name and the identifier of the parent resource. The same rule applies to the identifier of the parent resource. |
Only specific subsets of properties are expected in Asset name and domain ID. The other combinations result in this error. See the sections of the API import operations chapter for examples. |
| importCommandIdentifierNotDefined | Specify the criteria for identifying the {0}. |
The import command does not contain the identifier mandatory property. |
| importCommandNotIdempotent | You cannot change the {1} if the {0} is identified by {1}. |
You change the same property that you use to identify the resource. You update the name of an asset, identified by name and domain ID. |
| importCommandResourceAmbiguous | More than one {0} matches the specified criteria. | The identifier does not contain enough elements to uniquely identify a resource. |
| importCommandResourceNotFound | No {0} matches the specified criteria. |
A mandatory dependency for the resource does not exist. The asset type of an imported asset does not exist. |
| importCommandResourceTypeInvalid | The resource type is invalid. The supported resource types are: {0}. | You are trying to import a resource that is not currently supported or there resource type is misspelled. |
| importCommandResourceTypeNotDefined | The resource type is not defined. The available resource types are: {0}. |
The import command is missing the mandatory resourceType property. |
Asset errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandAssetAttributeValuesAmbiguous | The asset defines both ''value'' and ''values'' properties for one or more attributes. | The value and values fields are mutually exclusive. You must provide only one for each attribute defined in the import command for an asset or a complex relation. |
| importCommandAssetDisplayNameInvalidLength | The asset display name must have between {0} and {1} characters, but had {2} characters. | The asset display name length must be within the range defined in the error message. |
| importCommandAssetDomainNull | The domain for the asset is not defined. | The domain is mandatory for the assets that need to be added during import or synchronization. |
| importCommandAssetNameInvalidLength | The asset name must have between {0} and {1} characters, but had {2} characters. | The asset name length must be within the range defined in the error message. |
| importCommandAssetNameNull | The asset name is not defined. | The asset name is mandatory for the assets that need to be added during import or synchronization. |
| importCommandAssetTypeNull | The asset type is not defined. | The asset type is mandatory for the assets that need to be added during import or synchronization. |
Asset type errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandAssetTypeNameInvalidLength | The asset type name must have between {0} and {1} characters, but had {2} characters. | The asset type name length must be within the range defined in the error message. |
Attribute type errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandAttributeTypeNameInvalidLength | The attribute type name must have between {0} and {1} characters, but had {2} characters. | The attribute type name length must be within the range defined in the error message. |
Community errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandCommunityNameInvalidLength | The community name must have between {0} and {1} characters, but had {2} characters. | The community name length must be within the range defined in the error message. |
| importCommandCommunityNameNull | The community name is not defined. | The community name is mandatory for the communities that need to be added during import or synchronization. |
Complex relation errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandComplexRelationRelationsDuplicated | Complex Relation relations are duplicated for relation type ID: ''{0}''. | The import command contains a duplicated relation that was defined both in the command and in the identifier. |
| importCommandComplexRelationRelationsNull | The relations for the complex relation are not defined. | The identifying relations are mandatory for the complex relations that need to be added during import or synchronization. |
| importCommandComplexRelationTypeNull | The complex relation type is not defined. | The complex relation type is mandatory for the complex relations that need to be added during import or synchronization. |
Complex relation type errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandComplexRelationTypeNameInvalidLength | The complex relation type name must have between {0} and {1} characters, but had {2} characters. | The complex relation type name length must be within the range defined in the error message. |
Domain errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandDomainCommunityNull | The community for the domain is not defined. | The community is mandatory for the domains that need to be added during import or synchronization. |
| importCommandDomainNameInvalidLength | The domain name must have between {0} and {1} characters, but had {2} characters. | The domain name length must be within the range defined in the error message. |
| importCommandDomainNameNull | The domain name is not defined. | The domain name is mandatory for the domains that need to be added during import or synchronization. |
| importCommandDomainTypeNull | The domain type is not defined. | The domain type is mandatory for the domains that need to be added during import or synchronization. |
Domain type errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandDomainTypeNameInvalidLength | The domain type name must have between {0} and {1} characters, but had {2} characters. | The domain type name length must be within the range defined in the error message. |
External identifier errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandExternalIdentifierExternalEntityInvalidLength | The {0} external entity ID must have between {1} and {2} characters, but had {3} characters. | The external entity ID length must be within the range defined in the error message. |
| importCommandExternalIdentifierExternalEntityNull | The {0} external entity ID must be provided if the external system ID is provided. Specify the external entity ID. | The external entity ID is mandatory when you provided an external system ID. |
| importCommandExternalIdentifierExternalSystemInvalidLength | The {0} external system must have between {1} and {2} characters, but had {3} characters. | The external system ID length must be within the range defined in the error message. |
| importCommandExternalIdentifierExternalSystemNull | The {0} external system ID must be provided if the external entity ID is provided. Specify the external system ID. | The external system entity ID is mandatory when you provided an external entity ID. |
Mapping errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandMappingExternalEntityIdInvalidLength | The external entity ID must have between {0} and {1} characters, but had {2} characters. | The external entity ID length must be within the range defined in the error message. |
| importCommandMappingExternalEntityIdNull | The external entity ID is not defined. | The external entity ID is mandatory for the mappings that need to be added during import or synchronization. |
| importCommandMappingExternalSystemIdInvalidLength | The external system ID must have between {0} and {1} characters, but had {2} characters. | The external system ID length must be within the range defined in the error message. |
| importCommandMappingExternalSystemIdNull | The external system ID is not defined. | The external system ID is mandatory for the mappings that need to be added during import or synchronization. |
| importCommandMappingResourceAmbiguous | More than one mapping matches the specified criteria. | The input for the mapping (JSON command or CSV/Excel content) contains reference to the resources via multiple properties (UUID, community, domain or asset). |
| importCommandMappingResourceNotFound | No mapping matches the specified criteria. | A mapping could not be found for the provided identifier(s). |
Role errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandRoleNameInvalidLength | The role name must have between {0} and {1} characters, but had {2} characters. | The role name length must be within the range defined in the error message. |
Status errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandStatusNameInvalidLength | The status name must have between {0} and {1} characters, but had {2} characters. | The status name length must be within the range defined in the error message. |
Tag errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandTagNameInvalidLength | The tag name must have between {0} and {1} characters, but had {2} characters. | The tag name length must be within the range defined in the error message. |
User errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandUserNameEmpty | The user name cannot be empty. | You must provide a value for the user name. |
User group errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importCommandUserGroupNameInvalidLength | The user group name must have between {0} and {1} characters, but had {2} characters. | The user group name length must be within the range defined in the error message. |
General errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importError | The import failed. | A generic import error for issues that have no obvious solution. |
| synchronizationError | The synchronization failed. | A generic synchronization error for issues that have no obvious solution. |
| errorHelp | Line {0} contains the following error(s): | N/A |
| importErrorsLines | Line {0} contains the following error(s): | N/A |
| importProcessingError | The input processing did not complete successfully. | A generic processing error for issues that have no obvious solution. |
| importValidationError | The input validation did not complete successfully. | A generic input validation error for issues that have no obvious solution. |
API request errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importRequestFileNotSpecified | The request must contain the file ID or the file stream, but not both. | The file ID and file stream are mutually exclusive .You must provide at least one of the two. |
| importRequestFileNotSpecifiedHelp | Enter the file ID or file stream in the request. | N/A |
| importRequestFileNameBlank | You provided a file stream. You must also provide a file name. | You must provide the file name if you used file stream as an input parameter. |
Import parameters validation errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importParametersBatchSizeInvalidValue | The expected batch size value is between {0} and {1} but was {2}. | The batch size must have a value within the range defined in the error message. |
| importParametersCsvSeparatorNull | The CSV separator must be provided. Specify the CSV separator. | The CSV separator character is a mandatory parameter. |
| importParametersCsvQuoteNull | The CSV quote character must be provided. Specify the CSV quote character. | The CSV quote character is a mandatory parameter. |
| importParametersCsvEscapeNull | The CSV escape character must be provided. Specify the CSV escape character. | The CSV escape character is a mandatory parameter. |
| importParametersExcelSheetAmbiguous | You cannot provide the Excel sheet index and the sheet name at the same time (sheet index = ''{0}'', sheet name = ''{1}''). | The Excel sheet index and Excel sheet name parameters are mutually exclusive. You can only provide one at a time. |
| importParametersFileIdNull | The file ID must be provided. | The file ID is a mandatory parameter. |
| importParametersSynchronizationIdBlank | The synchronization ID must be provided for a synchronization operation. Specify the synchronization ID. | The synchronization ID is mandatory for synchronizations. |
| importParametersSynchronizationIdInvalidLength | The synchronization ID must have between {0} and {1} characters, but was {2}. | The synchronization ID length must be within the range defined in the error message. |
| importParametersSynchronizationIdNotNull | The synchronization ID must not be provided for an import operation. | The synchronization ID must not be provided for regular import. |
| importParametersTemplateBlank | The JSON template must be provided. | The JSON template is a mandatory parameter. |
| importParametersTemplateInvalid | The JSON template is invalid. | The JSON template does not follow the JSON syntax. |
| importParametersTemplatePlaceholderMissing | The JSON template must contain at least one placeholder. | You must provide at least one placeholder in the JSON template, representing the data that must be retrieved from a tabular file. |
| importParametersTemplatePlaceholderInvalid | The JSON template must contain placeholders that are positive integer numbers. | The JSON template contains '${0}' as placeholder. |
| synchronizationAdministrationParametersSynchronizationIdBlank | The synchronization ID must be provided. Specify the synchronization ID. | The synchronization ID is a mandatory parameter for synchronization administration. |
| synchronizationAdministrationParametersSynchronizationIdInvalidLength | The synchronization ID must have between {0} and {1} characters, but was {2}. | The synchronization ID must have a value within the range defined in the error message. |
JSON input parsing errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importJsonParsingGeneralError | An error occurred when parsing the JSON file. | N/A |
| importJsonParsingErrorWithPosition | An error occurred when parsing the JSON file, caused by: {0}, localized at line = {1} and column = {2}. | N/A |
Template parsing errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importJsonTemplateGeneralError | An error occurred when parsing the JSON template, caused by: {0}. | The JSON template does not follow the JSON syntax. |
Excel parsing errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importExcelParsingGeneralError | An error occurred when parsing the Excel file, caused by: {0}. | The file you provided is not a valid Excel file. |
| importExcelParsingEmptyFile | The Excel sheet {0} contains no data. | The Excel sheet used for import or synchronization is empty. |
Table view config parsing errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importTableViewConfigParsingError | An error occurred while parsing TableViewConfig. | The table view configuration does not follow the JSON syntax or contains unexpected JSON nodes. |
Concurrent import errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importConcurrentAddEntityWithSameId | The concurrent import caused a constraint violation. | More than one import or synchronization job running concurrently contains the same resource that needs be added. |
| importConcurrentAddEntityWithSameIdHelp | This can happen when the same resource is added twice. Ensure multiple import batches do not contain the same resources. | N/A |
| importConcurrentEntityUpdate | The concurrent import caused an update exception. | More than one import or synchronization job running concurrently contains the same resource that needs be updated. |
| importConcurrentEntityUpdateHelp | This can happen when the same resource is updated in parallel. Ensure multiple import batches do not contain the same resources. | N/A |
Synchronization errors
| Error code (visible in dgc.log) |
Structure of error message | Reason |
|---|---|---|
| importSynchronizationFinalizationAlreadyRunning | You cannot start the synchronization import for synchronization ID (''{0}'') while a cleanup is in progress for it. | The finalization step of a synchronization is in progress. During this time, you cannot run any other synchronization operation for the same synchronization ID. |
| importFinalizationSynchronizationAlreadyRunning | You cannot start the synchronization cleanup for synchronization ID (''{0}'') while an import is in progress for it. | The synchronization operation is in progress. During this time you cannot run the finalization step for the same synchronization ID. |