ESHOPMANESHOPMAN Logo
Our Blog

Navigating HubSpot App Migration: Avoiding Install Blocks and Mastering Marketplace Listings

Hey ESHOPMAN community! As experts focused on bringing robust e-commerce capabilities right into HubSpot, we often see developers and businesses grappling with the intricacies of the HubSpot ecosystem. Recently, a fascinating discussion in the HubSpot Community caught our eye, highlighting some critical challenges for anyone migrating a public OAuth app. It’s a deep dive into the technical trenches, but the insights are gold for anyone building on HubSpot, especially if your apps power businesses looking to create a free website for selling products or scale their existing online stores.

The original poster, Durvankur from Labra, laid out a detailed scenario concerning their public OAuth apps, Labra QA and Labra (Production). They’d successfully migrated their internal QA app to the new 2026.03 platform version, but hit a snag: existing installs continued to work, but new installs started failing with an "installation limit exceeded" error. This happened because their QA app had 56 installs, exceeding the 25-install cap for unlisted Marketplace apps on the new platform version. Their production app, with over 65 installs, was still on the legacy platform, and they were rightly concerned about replicating this issue.

The HubSpot App Migration Conundrum: Key Challenges

This discussion really brings to light several crucial points for developers and RevOps teams:

1. The Unlisted App Install Limit

This was the core revelation: migrating an unlisted public app to 2026.03 enforces a strict 25-install limit for *new* installations. Existing installs remain active, but any new portal connections after migration will be blocked if you're over that threshold. HubSpot Support confirmed this behavior as expected. This means if your app is public and has more than 25 installs, you absolutely cannot migrate it to the new platform version without first getting it listed on the Marketplace.

2. Marketplace Listing Requirements: Legacy CRM Cards vs. App Cards

The original poster also noted that their QA app’s Marketplace listing was rejected due to using Legacy CRM Cards. This is a clear signal from HubSpot: the future is with App Cards (UI Extensions). If you’re planning a migration, ensure your app fully utilizes the new UI Extensions and deprecates any legacy CRM card functionality. This isn't just a preference; it's a requirement for Marketplace approval.

3. Managing QA Environments for Public Apps

How do you effectively test a public app internally if your QA environment needs more than 25 internal test portals, but migrating it to 2026.03 imposes that cap? The original poster asked if two listings are allowed – one public for production, and one hidden/unlisted for QA – specifically to bypass the 25-install cap for internal testing. This highlights a potential gap in the current developer workflow for robust QA of widely installed public apps.

4. Avoiding Production Downtime During Migration

The biggest fear for any developer is interrupting customer service. The question of how to avoid blocking new installs in production while migration and listing are in progress is paramount. Similarly, rolling out new App Cards with feature flags or gradual enablement to ensure existing installs remain uninterrupted is a critical concern.

Actionable Insights for Your HubSpot App Migration

While the community thread didn't provide direct answers from HubSpot staff, it clearly outlined the challenges and implied the necessary strategic shifts. Here’s what we can glean:

  1. Prioritize Marketplace Listing BEFORE Migration for Public Apps: If your public app has more than 25 installs, you absolutely must get it approved and listed on the HubSpot Marketplace *before* you initiate the migration to 2026.03. The listing process itself acts as the 'unlock' for unlimited installs on the new platform.

  2. Embrace App Cards (UI Extensions): Start developing and testing your App Cards now. Ensure they replicate and improve upon any functionality provided by legacy CRM cards. This is non-negotiable for Marketplace approval on the new platform.

  3. Strategic QA Planning: For QA environments of public apps, the 25-install cap for unlisted 2026.03 apps is a significant hurdle. Consider these options:

    • If you need more than 25 internal test portals, keep your QA app on the legacy platform until very close to your production migration, or explore if a separate, truly 'internal' app type (not public OAuth) can serve your QA needs.
    • Alternatively, you might need to manage your internal test portals more rigorously, ensuring you stay under the 25-install limit for your 2026.03 QA app, or push for a 'hidden' Marketplace listing for QA if HubSpot allows it.

  4. Phased Rollouts and Feature Flags: For production apps, plan to use feature flags or gradual enablement strategies when rolling out new App Cards post-migration. This minimizes risk and ensures a smooth transition for your existing customer base. The goal is zero downtime and seamless user experience.

  5. Proactive Communication with HubSpot: As the original poster did, leverage HubSpot Support and the Developer Community. For complex migration paths, especially with high-volume apps, direct engagement with the Marketplace or Developer Platform team is invaluable. Don't hesitate to open tickets and ask for guidance.

The original poster shared the migration command they used for their QA app:

hs app migrate \
--app-id \
--name “Labra QA App” \
--dest ./labra-app-migrated \
--platform-version 2026.03 \
--account

This command is crucial for initiating the migration, but remember, the technical execution is only one part of the puzzle; the strategic planning around install limits and Marketplace listing is equally, if not more, important.

ESHOPMAN Team Comment

This community discussion perfectly illustrates why a deep understanding of HubSpot's developer platform changes is vital for anyone building e-commerce solutions. The 25-install cap for unlisted apps on the new platform version is a significant gotcha that could severely disrupt businesses relying on these integrations. We strongly advocate for proactive planning, early engagement with HubSpot's developer resources, and prioritizing Marketplace listing to ensure seamless transitions for apps powering online stores within the HubSpot ecosystem.

Migrating a public HubSpot app is not just a technical task; it's a strategic undertaking. For businesses leveraging HubSpot to manage their sales and customer relationships – whether they're just starting to create a free website for selling products or managing complex e-commerce operations – the stability and functionality of their integrated apps are paramount. By understanding these nuances and planning meticulously, developers can ensure their apps continue to provide uninterrupted value, supporting the growth and success of HubSpot users worldwide.

Share: