Netlify Docs
Ask Netlify

Contact

Manage data /Connect /

Troubleshooting tips for Netlify Connect

This feature is available on Connect Enterprise plans.

This document provides troubleshooting tips for Netlify Connect.

# Find your data layer ID

Need your data layer ID for a support conversation or for a manual set-up step for a data source? Once you add a data layer, you can find the ID in the URL for the data layer’s pages in the Netlify UI.

The URL is formatted as https://app.netlify.com/teams/YOUR-TEAM-NAME/connect/data-layers/YOUR-DATA-LAYER-ID/...

If you are in the initial flow to create and configure a new data layer, you can find the ID for the data layer in the URL starting from the add data sources step.

If you have already created a data layer, the ID will appear in the URL as you navigate through the different Netlify UI pages for that data layer:

  1. Navigate to the
    Connect
    page for your team in the Netlify UI.
  2. Select the data layer from the Data layers list.
  3. Find the data layer ID in the URL.

# Find your data layer’s webhook URL

Depending on your setup, you may need to manually create a webhook on your data source that notifies Connect when data changes. Or, perhaps you want to make a POST request to manually trigger updates. In both of these scenarios, you need the webhook URL for your data layer:

  1. Navigate to the
    Connect
    page for your team and select the data layer from the Data layers list.
  2. Select Data layer settings.
  3. Find the Webhook URL under
    General Data layer information
    . It is formatted as https://webhook.netlify-connect.com/hooks/data_layer/data_source/publish/{data_layer_id}.

# Find the slug for a data integration

While setting up a webhook on a data source or troubleshooting an error, you may need to refer to the slug for the data integration you’re using.

To find the slug:

  1. Navigate to the
    Extensions
    page for your team.
  2. Find the extension for the data integration and then select it.
  3. Review the URL to find the slug, which is the last part of the URL.

For example, if the URL for the Drupal data integration is https://app.netlify.com/teams/your-team-name/extensions/cms/drupal-content, the slug is drupal-content.

# Data integration for custom data source doesn’t show up as an option

If you try to add a custom data source to your data layer and the data integration for that data source doesn’t appear as an option in the Netlify UI, confirm that you have installed the integration for your team.

  1. In the Netlify UI, navigate to the
    Extensions
    page for your team.
  2. Find the data integration for the custom data source you wish to use and select it.
  3. If it’s not already installed, select Install.

If you can’t find the data integration or the integration is already installed, work with the integration developer to ensure that it was published correctly.

If the above steps don’t seem to resolve this issue, contact support.

# Other questions about custom data sources

For help with a custom data source, refer to the data integration’s details page in the Netlify UI and any external documentation the page links out to. You can find the details page by navigating to

Extensions
and searching for the integration by name.

If you have questions, please contact the integration developer directly.

# Initial sync fails after configuring a data source

If you add a new data source and the initial sync isn’t successful, check the following:

  1. Confirm that you completed the steps to prepare your data source instance for Connect, if applicable. To review the preparation steps, check our documentation on how to add new data sources and filter for the data source type to reveal the instructions. If there are additional steps to take, the instructions include a section with a title that begins with Prepare, such as Prepare your Contentful instance.
  2. Confirm that the configuration details entered for your data source instance are correct. To review your settings:
    1. Navigate to the
      Connect
      page for your team in the Netlify UI.
    2. Select the data layer from the Data layers list, and then select Data layer settings.
    3. On the data layer settings page, select Data sources.
    4. Select the data source you want to review.
    5. If there are any errors, select Edit, update the fields as needed, and then select Save.
  3. After you make any changes, manually trigger a sync.

If the above steps don’t seem to resolve this issue, contact support.

# Changes in data source don’t trigger a sync

Connect relies on your data source to send a notification whenever data changes. If a change does not trigger a sync in Connect, check the settings on your data source:

  1. Confirm that a webhook with your data layer’s webhook URL exists. If a webhook doesn’t exist, you likely need to add one manually. This is often a prerequisite step for adding a data source to Connect, especially custom data sources. Review our documentation on how to add and configure data sources.
  2. Confirm that the webhook is set to trigger on the data types and events you want to sync. For example, you may be missing a “product” type or a “delete” event. Refer to the documentation for your data source to learn more about configuring webhooks on their system.
  3. Confirm that the webhook is enabled.

If the above steps don’t seem to resolve this issue, contact support.

# Handle large Contentful or WordPress payloads

If you encounter errors syncing a Contentful data source due to the payload size, edit the data source to lower the Page limit value from the default of 1000 so that data is retrieved in smaller batches.

Similarly, if your WordPress data source has errors due to the payload size, edit the data source to lower the Per page value from the default of 100 so that data is retrieved in smaller batches.

# Responses from the data layer API are slow

Responses to queries that are larger than 9 KB are not cached. If a large response is not cached, each subsequent query for the data will take a similar length of time to process.

To get maximum performance from your data layer’s API, we recommend that you take advantage of pagination by using skip and limit filters in your queries. If that’s not possible, consider making multiple small queries that return smaller response bodies, which can be cached separately.

Note that a data sync clears the edge cache entries for the modified data and that updates to more than 100 or so entries purge the cache for the entire data layer. As a result, initial queries following a data sync may take longer than usual.

Learn more about how we calculate query complexity.

# Clear database cache and sync again

If you are debugging an issue and want to clear out your data layer’s database and start fresh, you can use the clear cache option.

  1. Navigate to the

    Connect
    page for your team and select the data layer from the Data layers list.

  2. In the Activity section, select

    Trigger sync Clear cache and sync from all data sources
    .

Netlify will clear the database cache and start syncing the data from all sources again to create a fresh database for your data layer.

# Sync event is complete but the API reflects old data

If the Activity section reflects a successful data sync but the data layer API still reflects old data, make sure your API isn’t using a pinned data revision. If a data revision is pinned, successful syncs will continue to generate new data revisions but the API will always use the pinned version.

  1. Navigate to the
    Connect
    page for your team in the Netlify UI.
  2. Select the data layer from the Data layers list.
  3. Check the data layer overview to confirm whether or not the API is using a pinned revision.

If a specific data revision is pinned and you want to check the data in a revision before unpinning or updating the pin, you can query the data for that specific revision.

# Trigger builds automatically for a specific branch

When data changes in your data layer, Netlify automatically builds and deploys the production branch of all connected sites. Currently, it’s not possible to specify a different branch when you connect a site.

If you would like to trigger builds for a different branch, you can follow this workaround to create a Netlify build hook and add it as a custom webhook to your data layer.

  1. First, create a build hook for your site. Navigate to
    Site configuration Build & deploy Continuous deployment Build hooks
    .
  2. Select Add build hook.
  3. Enter a Build hook name and select the Branch to build, then select Save.
  4. Find the new build hook in the list and copy the webhook URL.
  5. Now, create a custom webhook for your data layer. Navigate to the
    Connect
    page for your team.
  6. Select the data layer from the Data Layers list, and then select Data layer settings.
  7. On the data layer settings page, select Custom webhooks.
  8. Select Add a custom webhook.
  9. Enter a Name for this webhook.
  10. Paste the copied build hook into the URL field for this webhook.
  11. Select Create custom webhook to add the webhook to your data layer.

Now, whenever your data layer updates, Netlify automatically triggers the custom webhook to start a new build and deploy for the specified branch.

# API query does not return the expected types and fields

If you make a query to your data layer’s API and not all of the data you expect is returned, make sure your API token has the correct scopes for that data.

  1. Navigate to the

    Connect
    page for your team in the Netlify UI.

  2. Select the data layer from the Data layers list, and then select Data layer settings.

  3. On the data layer settings page, select API access control.

  4. In the API scopes section, find the scope for the data required.

  5. Select the scope to expand the details and review the list of tokens, fields, and types that the scope applies to.

  6. If your token is not on the list, use one of the tokens listed instead. Or generate a new token with that scope.

# Get help with Connect client

If you use the Connect client to query your data layer’s GraphQL API, refer to the connect-client readme for troubleshooting tips and support.

← Usage & billing →