Troubleshooting
This page contains answers to common questions and issues that users encounter when using Port, organized by topic.
Choose a topic below to find the relevant answers and solutions:
- General - account, organization, catalog, and security questions.
- Ocean integrations - installation, validation, mapping, and connectivity issues.
- Actions - actions stuck in progress and backend setup.
- Port execution agent - agent startup, authentication, Kafka, and TLS errors.
- GitHub - live events, entity deletion, pagination, and mapping issues.
- GitLab - resync errors, token scopes, and version compatibility.
- Azure DevOps - deleted repositories, sync, and ingestion issues.
API
To troubleshoot requests to Port's API, refer to the API troubleshooting section.
FAQ
Common causes include invalid JQ expressions, missing or null entity identifiers, incorrect property paths, unsupported kind values, or missing permissions in the source tool. Check the integration's Event log for the specific failure.
See Ocean integration troubleshooting for diagnostic steps.
Common causes include property paths that do not match the source object's structure, transformation errors, and entity identifiers that resolve to empty values. The Event log identifies transformation errors, and a JQ playground can help you validate the expression against the source object.
Open the Connectors page, select the integration, and use the Event log for integration and mapping details. The Event log and Audit log provide more detailed failure information than the monitoring tips.
Check that Port service hooks exist in Azure DevOps and review the integration event log for abort or resync_aborted entries. If the previous run was interrupted, trigger a manual full resync from Connectors.
See Azure DevOps troubleshooting for the full diagnostic flow.
The sync kind did not fail completely, but at least one fetch, mapping, or ingestion stage reported failures. Review the sync status details and logs to identify the objects or stage that failed.
See monitoring and sync status for status definitions.