Troubleshooting HubSpot Writer
The following are known limitations or issues with the HubSpot Writer:
The HubSpot Writer does not support writing attachments (files, images, PDFs, documents) to specific objects. The adapter does not allow uploading files via SQL-based operations—objects like Files are exposed only as read-only views.
The only exception for attachments is the Engagements object, which has an attachments field that accepts a JSON string. However, direct file uploads are not supported even for this object.
OAuth refresh tokens expire based on HubSpot's configured token lifetime. If a refresh token expires, you will need to generate a new refresh token through the OAuth authorization flow and update the HubSpot Writer configuration.
Private App tokens can be revoked or regenerated in HubSpot. If a token is revoked, the HubSpot Writer will fail authentication until the configuration is updated with a valid token.
The HubSpot API has rate limits that vary by subscription tier. Exceeding these limits will result in throttling or failed requests. Configure appropriate batch policies to stay within rate limits.
Column mappings in the Tables property must match the exact property names in HubSpot. Property names are case-sensitive and must match HubSpot's internal property names.
Key columns specified in the keycolumns parameter must uniquely identify records in HubSpot for UPDATE and MERGE operations. Using non-unique key columns will result in unpredictable behavior.
Common Error Messages and Solutions
- Authentication Failed
Cause: Invalid credentials or expired tokens.
Solution: Verify that your Client ID, Client Secret, and Refresh Token (for OAuth) or Private App Token (for Private App Token auth) are correct. For OAuth connections, regenerate the refresh token if it has expired. For Private App Token, verify the token has not been revoked in HubSpot.
- Rate Limit Exceeded
Cause: Too many API requests sent to HubSpot within the allowed time window.
Solution: Increase the batch interval in the BatchPolicy property to reduce request frequency. Review your HubSpot subscription tier's rate limits and adjust your integration accordingly. Consider implementing exponential backoff for retry logic.
- Property Not Found
Cause: The specified property name in the column mapping does not exist in HubSpot or is misspelled.
Solution: Verify the property name matches exactly as it appears in HubSpot (property names are case-sensitive). Check that the property exists for the target object type. Use HubSpot's API documentation or property settings to confirm correct property names.
- Missing Required Property
Cause: A required property for the HubSpot object is not included in the column mapping.
Solution: Review the required properties for the target object in HubSpot. Update the columnmap parameter in the Tables property to include all required properties with appropriate source column mappings.
- Invalid Key Column
Cause: The key column specified in keycolumns does not uniquely identify records or does not exist.
Solution: Verify that the key column(s) specified uniquely identify records in HubSpot. For Contacts, email is typically used as the key column. For Companies, domain is common. Ensure the key column exists in both the source data and HubSpot object.
- Scope Permission Denied
Cause: The HubSpot app does not have the necessary write scope for the target object.
Solution: Review and update the scopes configured for your HubSpot app (OAuth or Private App). Ensure the app has the appropriate write scope for the object you're trying to write to (e.g., crm.objects.contacts.write for Contacts).
- Batch Write Failed
Cause: One or more records in a batch failed validation or exceeded size limits.
Solution: Check the detailed error message for specific validation failures. Common issues include data type mismatches, exceeding character limits for text fields, or invalid enum values. Reduce the batch size in BatchPolicy if batches are too large.
- Connection Timeout
Cause: Network connectivity issues or HubSpot service unavailability.
Solution: Check network connectivity to HubSpot's API endpoints. Verify that there are no firewall restrictions blocking HTTPS traffic to HubSpot. Check HubSpot's status page for any service disruptions.
Best Practices for Troubleshooting
Enable debug logging in Striim to capture detailed error messages and API responses from HubSpot.
Test connectivity to HubSpot using a simple object write (e.g., a single Contact) before configuring complex pipelines.
Use HubSpot's API documentation to verify property names, required fields, and data types for target objects.
When troubleshooting OAuth issues, use tools like Postman or curl to verify that tokens can be generated successfully outside of Striim.
Monitor the Striim application metrics to identify performance bottlenecks, error rates, and batch processing statistics.
Start with small batch sizes and gradually increase them while monitoring for errors and rate limit warnings.
Implement appropriate error handling by configuring the ApplicationErrorCountThreshold and IgnorableExceptionPattern properties.
Keep track of HubSpot API changes and version updates that may affect object properties or authentication requirements.
For complex troubleshooting scenarios, contact Striim support with detailed logs, configuration details, and a description of the issue.