> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve issues and errors related to interactive diagram parsing in Cognite Data Fusion.

### Prerequisites

* Make sure your assets exist in CDF.

* Check for SHX text embedded in the diagram file. If present, set `configuration.annotationExtract = True` to override overlapping OCR text. For more information, see [API documentation](/api-reference/concepts/20230101/engineering-diagrams).

* Ensure the asset names (or any other fields in use) match the tags in the file. If they don't match, do the following:

  * Create an alias for the asset name to better match the tags in the file.

  * Set `partialMatch` and `minTokens`.

### Tags are recognized incorrectly

* **I is recognized as T. For example, PI/TI is recognized as PT/TT**

  PI/TI tags often don't exist in the asset hierarchy; if they do, PT/TT tags may be their closest relatives. By default, we correct `I` to `T` if misread. Use [configuration substitutions](/api-reference/concepts/20230101/engineering-diagrams) to turn this off.

* **Wildcard tags are being linked to multiple tags**

  Add aliases to tags during diagram detection. For example, if `11-V-6x66` should link to both `11-V-6166` and `11-V-6666`, add `11-V-6x66` as an alias.

  The *entities* field looks like this:

  ```bash theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}
  {
    "entities": [
      {
        "name": ["11-V-6166", "11-V-6x66"]
      },
      {
        "name": ["11-V-6666", "11-V-6x66"]
      }
    ]
  }
  ```

* **Only a subset of the tag is recognized**

  Follow the steps in [Tags are not recognized](#tags-are-not-recognized) section to resolve this issue.

* **Large bounding box with widely spaced characters causes incorrect detection**

  Set `connectionFlags= ["natural_reading_order", "no_text_inbetween"]`. See [API documentation](/api-reference/concepts/20230101/engineering-diagrams) for more information.

* **Short false positives**

  Set `configuration.customizeFuzziness.minChars`. See [API documentation](/api-reference/concepts/20230101/engineering-diagrams) for more information.

### Tags are not recognized

Use the OCR endpoint to see the raw OCR detection results. For more information, see the existing [OCR API endpoint](/api-reference/concepts/20230101/engineering-diagrams). Currently, the SDK is not available.

Use the Python code below in the Cognite Jupyter Notebook.

```python theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}}

    from cognite.client import CogniteClient
    from cognite.client.config import FusionNotebookConfig

    client = CogniteClient(
     FusionNotebookConfig(api_subversion="20230101-beta")
    )

    file_id = ... # put in your file id

    from typing import Any
    from cognite.client.data_classes.contextualization import DiagramConvertResults
    def ocr(client, file_id: int, start_page: int = 1, limit: int = 50) -> list[dict[str, Any]]:
            """Get ocr text from a file that has been through diagram/detect before.

     Args:
     file_id (int): file id
     start_page (int): First page to get ocr from.
     limit (int): The maximum number of pages to get ocr from.
     Returns:
     list[dict[str, Any]]: List of OCR results per page.
     """

     response = client.diagrams._camel_post(
                "/ocr",
                json={"file_id": file_id, "start_page": start_page, "limit": limit},
     )
     items = response.json()["items"]
            assert isinstance(items, list)
            return items

    def ocr_annotation_to_detect_annotation(ocr_annotation: dict[str, any]) -> dict[str, any]:
     bounding_box = ocr_annotation["boundingBox"]
     vertices = [
     {"x": x, "y": y}
                for x in [bounding_box["xMin"], bounding_box["xMax"]]
                for y in [bounding_box["yMin"], bounding_box["yMax"]]
     ]
            return {"text": ocr_annotation["text"], "region": {"shape": "rectangle", "page": 1, "vertices": vertices}}

    def create_ocr_svg(client, file_id: int):
            """
     Get OCR text for a single-page PDF and create an SVG that overlays it as rectangles on top of a raster image
     Args:
     file_id (int): The file ID of the file used to create an OCR SVG.
     Returns svg_link

     """

            # Verify one page, and also make sure OCR exists.
     detect_job = client.diagrams.detect(
     [{"name": "dummy"}], file_references=FileReference(file_id=file_id, first_page=1, last_page=1)
     )
     detect_result = detect_job.result

     file_result = detect_result["items"][0]
            if file_result["pageCount"] != 1:
                raise Exception("The file must have one page")

     ocr_result = ocr(client, file_id, 1, 1)[0]["annotations"]

     input_items = [
     {
                    "fileId": file_id,
                    "annotations": [ocr_annotation_to_detect_annotation(a) for a in ocr_result][
     :10000
     ],  # For now, a limit of the API
     }
     ]

     job = client.diagrams._run_job(
                job_path="/convert",
                status_path="/convert/",
                items=input_items,
                job_cls=DiagramConvertResults,
     )

     res = job.result

            return res["items"][0]["results"][0]["svgUrl"]

    # Create an SVG file with OCR overlap
    create_ocr_svg(client, file_id)
```

When the tags are not recognized, the characters in the text are misread, or there are unexpected leading or trailing characters, allow **character substitutions** in the [Detect annotations in engineering diagrams](/api-reference/concepts/20230101/engineering-diagrams) endpoint > **Request** > `configuration`.
For example, if there are unexpected leading or trailing characters, replace the leading or trailing characters with an empty string “”.