Knowledge Catalog (formerly Dataplex Universal Catalog) lets you import and export business glossaries
and entry links in bulk to manage your business vocabulary at scale. When you
run the import or export utility scripts, you can diagnose and resolve common
issues such as missing entry links, empty glossary exports, invalid glossary or
spreadsheet URLs, interrupted import jobs, and script network timeouts. For
more information, see
[About importing and exporting glossaries and entry links](https://docs.cloud.google.com/knowledge-catalog/docs/import-export-glossaries-entrylinks-overview.md.txt).

If you need help resolving an issue that isn't addressed in this document, see
[Cloud Customer Care](https://docs.cloud.google.com/support).

## Fix missing entry links in Knowledge Catalog

After you export entry links from Knowledge Catalog to a Google Sheet by
running the [export entry link utility](https://docs.cloud.google.com/knowledge-catalog/docs/export-entrylinks-sheets.md.txt),
you notice that some entry links (associations) are missing from the generated
Google Sheet.

This issue occurs if the export utility automatically skips entry links
because of the following conditions:

- Insufficient permissions (redacted resources): You don't have the required
  IAM permissions to view either the source entry or the
  target entry associated with the link.

- Invalid entry link type: The entry link uses an unsupported or unrecognized
  relationship type. Valid types are limited to `definition`, `related`, and
  `synonym`.

- Incomplete entry references: The entry metadata is missing required schema
  fields, causing the validation check to skip the resource.

To resolve this issue, perform the following checks:

- Verify permissions: Ensure you have permissions to view missing entry links. Confirm that the principal executing the script has been
  granted the
  [required roles](https://docs.cloud.google.com/knowledge-catalog/docs/export-entrylinks-sheets.md.txt#required_roles).

- Inspect execution logs: Check the terminal or script logs for warnings
  containing `Skipping redacted entrylink`. The logs output the specific
  resource IDs of the skipped entry links and the reason they were omitted.

- Check link schema validity: If you previously modified these links
  programmatically, verify that their properties match the schema requirements.

## No terms found in the glossary error

When you
[export glossaries to a Google Sheet](https://docs.cloud.google.com/knowledge-catalog/docs/export-glossaries-sheets.md.txt),
the execution fails or returns an empty result with the message
`No terms found in the glossary`, even though the business glossary contains
active terms.

This issue occurs if the script can't locate the specified glossary or lacks
the access permissions required to retrieve its contents. Common causes include:

- Incorrect glossary URL: The glossary URL configured in your execution parameters is incorrect or misspelled.
- Insufficient IAM permissions: The authenticated service account or user credentials running the script don't have permission to view or list terms within the target glossary.
- Glossary ID mismatch: The glossary ID specified in your script command doesn't match the actual glossary resource ID in Knowledge Catalog.

To resolve this issue, verify your configuration and permissions:

- Check the glossary ID: In the Google Cloud console, navigate to the
  Knowledge Catalog **Glossaries** page, select your glossary, and
  confirm that the resource ID matches the ID you are passing to the utility
  script.

- Verify IAM permissions: Confirm that your authenticated
  credentials (the service account or your impersonated user account) have been
  granted the
  [required roles](https://docs.cloud.google.com/knowledge-catalog/docs/export-glossaries-sheets.md.txt#required_roles).

- Validate the glossary URL structure: If you're passing a direct resource path
  or URL to the script, ensure it follows the correct Knowledge Catalog
  resource format:

  `projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID`

## Entries not found in Knowledge Catalog warning

During an [entry link import](https://docs.cloud.google.com/knowledge-catalog/docs/import-entrylinks-sheets.md.txt) operation,
the script pauses and displays a warning similar to the following:

    Found X entries not found in Knowledge Catalog. EntryLinks associated with
    these entries will be skipped. Continue with import? [y/N]:

This issue occurs if your Google Sheet contains entry links that reference
data assets or glossary terms that don't exist in Knowledge Catalog.

To resolve this issue, choose one of the following options:

- To proceed with a partial import, type `y` at the prompt. The utility imports
  all valid entry links and skips only the links that reference the missing
  resources.

- To cancel and fix the missing resources, type `n` to cancel the execution.
  Verify that the entry IDs in your source document exactly match the resource
  names in your Knowledge Catalog. Correct any missing resources or
  typographical errors, and then run the import script again.

## Troubleshoot Knowledge Catalog import job fails

If an import job is interrupted or fails midway through execution, you don't
need to restart the entire process or modify your source Google Sheet.

The utility tracks successfully imported batches using an archive folder in
your Cloud Storage staging bucket.

To resume the job, follow these steps:

1. Re-run the import utility. The utility detects the state of your previous
   run, it displays the following prompt:

       Found X existing file(s) in archive folder from a previous incomplete import
       Continue using existing files? [y/N]:

2. Type `y`. The utility skips the batches that were already successfully
   imported and processes only the remaining files.

## Script timeouts or SSL errors during execution

While running the import or export utility script, the execution halts,
times out, or returns SSL errors in your terminal.

This issue occurs because of the following network-level errors:

- Corporate proxy or firewall interception: A security proxy or firewall is intercepting and inspecting HTTPS traffic, which invalidates the SSL certificates.
- Active VPN restrictions: Your VPN configuration restricts outbound traffic to certain Google Cloud APIs or Google Sheets endpoints.
- Local network instability: A temporary drop in internet connectivity interrupted the session.

To resolve these network issues, try the following steps:

- Ensure you have a stable network connection.

- Inspect proxy and firewall settings

- Check your VPN configuration.

- Rely on built-in retries: The utility script has built-in retry logic for
  transient network glitches. If the network drop is momentary, wait for the
  script to finish its retry attempts before restarting the execution.

## Invalid spreadsheet URL error

When you attempt to run an import or export utility, the command-line interface
returns an `Invalid spreadsheet URL` error and halts execution.

This issue occurs if the script can't parse the provided Google Sheet's link or
doesn't have authorization to view the file. Common causes include:

- Malformed URL: The URL doesn't match the standard Google Sheets path format.
- Missing spreadsheet ID: The path is missing the unique alphanumeric ID that points to your specific sheet.
- Access restrictions: Your authenticated service account doesn't have permission to view or edit the sheet, preventing the utility from validating the link.

To resolve this issue, verify your spreadsheet link and access settings:

- Validate the URL prefix: Ensure that the spreadsheet URL you pass to the
  utility begins with the following standard Google Sheets path:
  `https://docs.google.com/spreadsheets/`

- Verify the spreadsheet ID: Confirm that the URL includes your sheet's unique
  ID. A valid URL should follow this structure:
  `https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit`

- Check access permissions: Open the Google Sheet in a browser, click **Share** ,
  and confirm that you have added your service account email
  as an **Editor**.

## Resolve invalid glossary URL errors

When you attempt to run an import or export utility for glossaries, the
command-line interface returns an `Invalid glossary URL` error and halts
execution. Verify that there is no invalid glossary URL in your parameters.

This issue occurs if the script can't parse the provided Knowledge Catalog
glossary resource path or doesn't have authorization to view the resource.
Common causes include:

- Malformed resource path: The resource path doesn't match the standard Knowledge Catalog glossary path format.
- Incorrect ID: The path contains an incorrect project ID, region location, or glossary ID.
- Access restrictions or missing resource: The glossary doesn't exist, or your authenticated service account lacks the IAM permissions required to access it.

To resolve this issue, verify your glossary resource path and credentials:

- Validate the resource path structure: Ensure that the glossary path you pass
  to the utility matches the following standard Knowledge Catalog format:
  `projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID`

- Verify identifiers in the path: Use the correct project ID, location, and
  glossary ID.

- Confirm resource existence and access: Confirm that the glossary exists with
  the specified ID and your authenticated service account has been granted
  necessary IAM roles.

## View execution logs

The import and export utilities generate detailed execution logs as they run.
If your import job fails, check the logs for specific errors. These logs help
you audit the transfer process and identify skipped entries or formatting
warnings.

- Log location: The import and export utilities writes log files to the `logs/` directory in your local execution path.
- Log format: Each log file is appended with a timestamp so you can locate logs for a specific run.