How do you identify problems affecting your Heroku Connect sync?
Heroku Connect is a fully managed, bidirectional data sync service between Salesforce and Heroku Postgres that lets developers read and write Salesforce data using standard SQL. The sync is straightforward to set up and operates smoothly in the background, but when a field does not update as expected or data seems to lag, you do not need to guess what went wrong. You also do not need to click through multiple dashboards to find the bottleneck.
Instead, you can look to a built-in utility that’s been included in the Heroku Connect CLI plugin for years. While most of us are used to using the Heroku CLI for logs and config vars, installing the specialized Heroku Connect CLI plugin unlocks a whole separate layer of data management tools.
The heroku connect:diagnose command acts as an immediate health check on your data pipeline. Running this audit can save engineering teams hours of manual troubleshooting by pointing out things like configuration mismatches instantly.
heroku connect:diagnose --verbose
Diagnosing connection... done
=== Connection: protected-ridge-4963
YELLOW: Salesforce API Version
The latest available Salesforce API version is 66.0. Your connection is using version 55.0. You should re-create your connection to use the latest version.
https://devcenter.heroku.com/articles/heroku-connect-diagnose#check-salesforce-api-version
YELLOW: View/Modify All Data
Your Salesforce user is missing View All Data or Modify All Data permissions.
https://devcenter.heroku.com/articles/heroku-connect-diagnose#check-view-modify-all-data
GREEN: Number of Mappings
GREEN: Database Plan
GREEN: Heroku Postgres
GREEN: Data Locality
GREEN: Configured Logging
=== Account
RED: Unique Identifier
Read-write mappings require a unique identifier to be specified. Unique identifiers must be defined as unique External ID fields in Salesforce.
https://devcenter.heroku.com/articles/heroku-connect-diagnose#check-unique-identifier
GREEN: Binary Fields
GREEN: Calculated Fields
GREEN: Number of Fields
GREEN: Number of Large Text Area Fields
GREEN: Required Fields
GREEN: Salesforce Field Changes
GREEN: Database Field Changes
GREEN: IsArchived Field
GREEN: Polymorphic External ID
GREEN: Maximum Record Size
GREEN: Query Size
GREEN: sObject Is Not Supported by the Bulk API
SKIPPED: Synthetic Fields
SKIPPED: Synthetic Field/Unique Identifier Field Agreement
How the Heroku Connect diagnostic tool audits your data pipeline
When you run the diagnostic command, the CLI plugin analyzes your setup across two distinct operational areas. It prints a sequential log detailing high-level environment health first, followed by structural mapping and field property configurations.
- Connection environment checks: This category evaluates global settings and infrastructure boundaries. It verifies that your overarching connection endpoint, system permissions, and backing database tier have the correct capacity to maintain a stable, unthrottled synchronization pipeline.
- Mapping and field validation checks: This category audits the structural configurations governing your synced tables. It ensures that the database schema and Salesforce fields remain completely aligned by scanning for unsupported field types, missing constraints, or schema variations that could stall synchronization.
Common diagnostic warnings and how to fix them
The distinct advantage of the diagnostic output is that it replaces manual log hunting with human-readable status flags. When a diagnostic check fails or returns a warning, the status prefix changes from GREEN to YELLOW or RED. This highlights specific areas where your configuration deviates from best practices, making it a great tool to run as a proactive sanity check right before you deploy a major database migration or alter a Salesforce object schema.
Salesforce API Version warning
An outdated API version status means your configuration is using an old Salesforce API endpoint. This can lead to compatibility drift or missing feature support over time. Because the API version cannot be easily changed on an active connection, resolving this warning requires either submitting a support ticket with Heroku to change the API version or exporting your configuration and recreating the connection with a newer API version.
Field Type and Sync warnings
A warning for binary or calculated fields highlights data types that conflict with standard near-real-time sync expectations. Binary blobs are unsupported by the Bulk API queries used underneath, while cross-object formula fields calculate dynamically in Salesforce without updating the timestamps required to prompt a database sync.
- Binary fields: Base64 binary files stored in objects like attachments or documents are unsupported. Remove binary fields from your active configuration entirely. Instead of syncing heavy blobs, you could store files or images in an external object store like Amazon S3 and pass a simple text URL field between Salesforce and your database.
- Calculated fields: Cross-object formula and roll-up summary fields calculate dynamically on Salesforce and do not trigger a sync automatically. Review how these fields calculate to evaluate if you can replace them with standard database triggers, or read the Heroku Dev Center documentation to understand their manual polling constraints.
Salesforce Field Changes warning
A Salesforce field changes warning means a modification has occurred on the Salesforce side that is not reflected in your current mapping configuration. This usually happens when a field type changes or a new required field is added. To fix this, open your Heroku Connect dashboard and refresh the object schema to realign the mapping.
Database Field Changes warning
A database field changes warning flags a structural mismatch where the local Postgres database schema has drifted from the expected Heroku Connect configuration. Manually altering synced tables or column constraints can break the pipeline. You can resolve this by reverting conflicting database migrations or updating your mapping to match the new schema.
Keep your Heroku Connect pipeline green
The next time you are tweaking your application schema or notice an unexpected delay in record updates, skip the manual dashboard digging. Dropping back into the CLI to run heroku connect:diagnose gives you an instant, authoritative look at the health of your Salesforce data sync. It is a reliable, built-in utility that helps ensure your Heroku Connect data pipelines stay fully optimized and performant.
Keeping your data pipelines green is just the first step. If you want to take your integration further, use Heroku AppLink to securely connect and publish your Heroku apps to interact with Salesforce, Data 360, and Agentforce.
For an exhaustive breakdown of every diagnostic status flag and configuration best practices, check out the Heroku Connect Diagnostics documentation.
The post A 15-Second Health Check for Your Heroku Connect Data Pipeline appeared first on Heroku.