---
title: "A 15-Second Health Check for Your Heroku Connect Data Pipeline"
description: "Heroku Connect’s built-in CLI diagnostic utility addresses troubleshooting when Salesforce records lag or fields fail to update as expected, replacing manual dashboard searches with a focused health check. After installing the Heroku Connect CLI plugin, engineers can run heroku connect:diagnose --verbose to inspect connection-level settings and mapping or field configurations. The output reports sequential GREEN, YELLOW, RED, or SKIPPED statuses, with checks covering Salesforce API version, permissions, database plan, schema changes, field types, unique identifiers, and other constraints. Examples include an outdated API version, missing View All Data or Modify All Data permissions, binary or calculated fields, and Salesforce or Postgres schema drift; the text pairs these warnings with actions such as recreating or refreshing a connection, removing binary fields, or realigning mappings. Running the command before migrations or Salesforce schema changes provides an immediate view of configuration mismatches and sync bottlenecks."
---

# A 15-Second Health Check for Your Heroku Connect Data Pipeline

[Heroku](https://yomu.fyi/company/heroku) · Nick Prey · Jun 24, 2026

**Type:** Tutorial

## Summary

Heroku Connect’s built-in CLI diagnostic utility addresses troubleshooting when Salesforce records lag or fields fail to update as expected, replacing manual dashboard searches with a focused health check. After installing the Heroku Connect CLI plugin, engineers can run heroku connect:diagnose --verbose to inspect connection-level settings and mapping or field configurations. The output reports sequential GREEN, YELLOW, RED, or SKIPPED statuses, with checks covering Salesforce API version, permissions, database plan, schema changes, field types, unique identifiers, and other constraints. Examples include an outdated API version, missing View All Data or Modify All Data permissions, binary or calculated fields, and Salesforce or Postgres schema drift; the text pairs these warnings with actions such as recreating or refreshing a connection, removing binary fields, or realigning mappings. Running the command before migrations or Salesforce schema changes provides an immediate view of configuration mismatches and sync bottlenecks.

## Context

Unexpected field-update failures or lag in a Heroku Connect sync can require manual troubleshooting. The diagnostic utility is presented as a way to identify configuration mismatches and bottlenecks without searching through multiple dashboards.

## Approach / What changed

Install the Heroku Connect CLI plugin and run heroku connect:diagnose --verbose. The command audits connection-level environment settings plus mapping and field configurations, then reports each check with GREEN, YELLOW, RED, or SKIPPED status and links to relevant diagnostic guidance.

## Takeaways

- The diagnostic checks two areas: connection environment settings and mapping or field validation, including permissions, API version, database plan, schema changes, field types, and unique identifiers.
- A Salesforce API version warning may require a Heroku support ticket or exporting and recreating the connection with a newer API version because the version cannot be easily changed on an active connection.
- Binary fields are unsupported by the Bulk API, while calculated fields do not automatically trigger synchronization; the text recommends removing binary fields and reviewing alternatives for calculated fields.

**Tags:** [Heroku](https://yomu.fyi/topic/heroku), [Salesforce](https://yomu.fyi/topic/salesforce)

- Source: [Heroku](https://www.heroku.com/blog/health-check-for-your-heroku-connect-data-pipeline)
- Source URL: https://www.heroku.com/blog/health-check-for-your-heroku-connect-data-pipeline
- Ingested by Yomu: 2026-09-10T04:05:28.752Z

[Read original post](https://www.heroku.com/blog/health-check-for-your-heroku-connect-data-pipeline)