ESHOPMANESHOPMAN Logo
Our Blog

Troubleshooting HubSpot Custom Card Errors: A Developer's Guide

Troubleshooting HubSpot Custom Card Errors: A Developer's Guide

Custom cards in HubSpot can be incredibly powerful, extending the platform's functionality to meet specific business needs. But what happens when things go wrong during development? Figuring out where the failure occurred can be a frustrating process. Let's dive into a recent HubSpot Community discussion about finding detailed error logs for custom cards, and explore some solutions.

The Problem: Vague Error Messages

One community member ran into a common problem when uploading a custom card using the HubSpot CLI. The command hs project upload --debug returned a generic "Encountered server error building CARD" message. While the error message included a correlation ID, it lacked specific information about the root cause of the failure. This left the developer in the dark, struggling to pinpoint the exact location and nature of the problem.

{
buildName: 'crms_contact_extension_card',
userDefinedId: 'crms_contact_extension_card',
buildType: 'CARD',
status: 'FAILURE',
errorMessage: 'Encountered server error building CARD crms_contact_extension_card. correlation-id: 1ceb5af1-b312-454d-989b-c25c136954f8',
standardError: null,
startedAt: '2026-02-27T00:42:57.861Z',
finishedAt: '2026-02-27T00:43:58.159Z',
rootPath: '',
id: 'd5134a68-730f-43f1-afff-f36064160a06',
lightningBuild: false,
visible: true
}

The question was clear: how can developers access more detailed error information to effectively debug their custom cards?

The Solution: Community Input and Expert Advice

While the original post didn't receive a direct solution within the thread itself, the community moderator tagged several HubSpot developer experts, highlighting the need for better error reporting. Unfortunately, no concrete steps were provided in the discussion for finding more detailed logs. However, we can extrapolate based on common debugging practices and HubSpot's documentation:

1. Check the HubSpot Developer Documentation

HubSpot's official developer documentation is the first place to look. Search for sections related to custom cards, the HubSpot CLI, and error handling. While specific error code documentation may be limited, the general troubleshooting guides can provide valuable clues.

2. Utilize the Correlation ID

The correlation-id included in the error message can be helpful. While you might not be able to directly input this ID into a public-facing tool to get more details, HubSpot support may be able to use it to trace the error on their end. Contact HubSpot support and provide the correlation ID, along with details about your project, to see if they can provide more insights.

3. Review Your Code Methodically

Since detailed error logs aren't readily available, a thorough code review is essential. Check for common issues such as:

  • Syntax errors in your HubL, JavaScript, or CSS files.
  • Incorrect API calls or missing required parameters.
  • Issues with your card's JSON configuration.
  • Problems with data formatting or type mismatches.

4. Test in a Development Environment

Always test your custom cards in a development environment before deploying them to a live HubSpot portal. This allows you to catch errors early and avoid disrupting your users. Use the --debug flag with the HubSpot CLI to get more verbose output during the upload process.

5. Consider Using a Linter

A linter can help you identify potential problems in your code before you even upload it to HubSpot. Linters can detect syntax errors, style issues, and other common mistakes.

ESHOPMAN Team Comment

The lack of detailed error logs for custom card development is a pain point for many HubSpot developers. While the community discussion didn't provide a magic bullet, it highlights the importance of meticulous code review and leveraging HubSpot support when needed. We believe HubSpot should prioritize improving error reporting for developers to streamline the debugging process. For users of ESHOPMAN, remember that our support team is always available to help troubleshoot any issues that may arise during your integration with HubSpot.

Debugging can be time-consuming, but with a systematic approach, you can usually find the root cause of the problem. Keep an eye on HubSpot's developer documentation for updates and improvements to error reporting. In the meantime, lean on the community and HubSpot support when you get stuck.

Share: