Dependency Resolution
When deploying HubSpot metadata, the order matters. You can't create a property before its parent object exists, or a pipeline stage before the pipeline itself. HubSpot Deploy automatically handles these dependencies for you.
How It Works
Before any deployment begins, the system analyzes all selected items and arranges them in the correct order based on their dependencies. This ensures that:
- Parent objects are created before their children
- Foundation elements are deployed before dependent items
- Updates happen in a safe, predictable sequence
Deployment Order
Generated by node backend/scripts/deploymentOrder.js --write from
backend/src/metadata/catalog.js. Do not edit by hand.
Every selected item is sorted by its type's position in this list, and items of the same type by operation (manual → create → update → delete/archive), so one selection always produces the same steps in the same sequence — in the deployment preview and in the deployment itself.
| # | Metadata type | Deployable |
|---|---|---|
| 1 | Account Settings (account_settings) | compare only |
| 2 | HubSpot Owners (hubspot_owners) | compare only |
| 3 | HubSpot Teams (hubspot_teams) | compare only |
| 4 | HubSpot Roles (hubspot_roles) | compare only |
| 5 | HubSpot Users (hubspot_users) | compare only |
| 6 | HubSpot Brands (hubspot_brands) | compare only |
| 7 | Company Currency (company_currency) | create, update |
| 8 | Currency Exchange Rates (currency_exchange_rates) | create, update |
| 9 | Tax Rates (tax_rates) | compare only |
| 10 | Communication Subscription Types (communication_subscription_types) | compare only |
| 11 | Objects (objects) | never in a changeset |
| 12 | Standard Objects (standard_objects) | compare only |
| 13 | Custom Objects (custom_objects) | create, update |
| 14 | Association Definitions (association_definitions) | create, update |
| 15 | Association Limits (association_limits) | create, update |
| 16 | Property Groups (property_groups) | create, update |
| 17 | Standard Object Property (standard_object_property) | create, update |
| 18 | Custom Object Property (custom_object_property) | create, update |
| 19 | CRM Properties (crm_properties) | create, update |
| 20 | Pipelines (pipelines) | create, update |
| 21 | Pipeline Stages (pipeline_stages) | create, update |
| 22 | HubSpot Lists (hubspot_lists) | create, update |
| 23 | Custom Behavioral Events (custom_behavioral_events) | create, update |
| 24 | Property Validation Rules (property_validation_rules) | create, update |
| 25 | CMS Files (cms_files) | create, update, delete |
| 26 | Forms (forms) | create, update |
| 27 | CTAs (ctas) | create, update |
| 28 | Landing Pages (landing_pages) | create, update |
| 29 | Site Pages (site_pages) | create, update |
| 30 | CMS Domains (cms_domains) | compare only |
| 31 | CMS Blogs (cms_blogs) | compare only |
| 32 | Blog Authors (blog_authors) | create, update |
| 33 | Blog Tags (blog_tags) | create, update |
| 34 | Blog Posts (blog_posts) | create, update |
| 35 | URL Redirects (url_redirects) | create, update |
| 36 | HubDB Tables (hubdb_tables) | compare only |
| 37 | HubDB Rows (hubdb_rows) | create, update |
| 38 | Email Templates (email_templates) | create, update |
| 39 | Campaigns (campaigns) | create, update |
| 40 | Workflows (workflows) | create, update |
| 41 | Quote Templates (quote_templates) | compare only |
| 42 | Sequences (sequences) | compare only |
42 types carry an order. compare only means the type can
be extracted and diffed but HubSpot exposes no write surface for it, so it is
never deployed. A type absent from this table has no order and would be
deployed after everything listed here.
Why This Matters
Prevents Deployment Failures
Without proper ordering, deployments would fail when trying to create items that reference things that don't exist yet. For example:
- Creating a property for a custom object that hasn't been created yet
- Adding a pipeline stage to a pipeline that doesn't exist
- Creating a workflow that references a property that isn't deployed yet
Ensures Data Integrity
The correct order ensures that all relationships between metadata items are valid throughout the deployment process.
Handles Dependencies Between Types
When you select multiple items for deployment, the system automatically:
- Arranges them by type and operation, using the order above
- Deploys them sequentially, one group at a time
Ordering is per type, not per item: the list above says properties come after their object type, and nothing tracks that one specific workflow needs one specific list. If a step references an item that does not exist on the target and is not in this changeset, that step fails on HubSpot's answer.
Parent-Child Relationships
Some metadata types have special parent-child relationships:
Custom Objects and Properties
When you create a new custom object, you can include its properties in the same deployment. The system:
- Creates the custom object first
- Automatically includes all properties as part of the object creation
- Skips separate property deployment (they're already created)
This is more efficient than deploying the object and properties separately.
Pipelines and Stages
Similarly, when creating a new pipeline:
- The pipeline is created first
- All stages are included in the pipeline creation
- Individual stage deployments are skipped
Standard Objects and Properties
For built-in HubSpot objects (Contacts, Companies, Deals, etc.):
- The object already exists in HubSpot
- Properties are deployed separately
- The system ensures properties are deployed after the object is confirmed
Rollback Order
A rollback restores the state that was overwritten, in the reverse of the order above, so a dependent type is put back before the type it depends on.
Only updates are restored: a rollback puts back the snapshot taken before the item was overwritten, and an item this deployment created has no earlier state to return to. It stays on the target and has to be removed by hand.
What You Don't Need to Worry About
The dependency resolution system handles all of this automatically:
- ✅ You don't need to manually order items
- ✅ You don't need to know which items depend on others
- ✅ You can select any combination of items for deployment
- ✅ The system will figure out the correct order
Common Scenarios
Scenario 1: Deploying a New Custom Object with Properties
What you select:
- 1 custom object
- 10 properties for that object
What happens:
- System detects the custom object is being created
- Includes all 10 properties in the object creation payload
- Deploys everything in a single operation
- Marks individual properties as "deployed with parent"
Scenario 2: Deploying Mixed Metadata Types
What you select:
- 2 custom objects
- 5 properties for object A
- 3 properties for object B
- 1 pipeline
- 4 pipeline stages
What happens:
- Custom objects deployed first (A, then B)
- Properties included with their parent objects
- Pipeline deployed next
- Stages included with the pipeline
Scenario 3: Updating Existing Items
What you select:
- 3 property updates
- 1 workflow update
- 2 form updates
What happens:
- Properties updated first (they're earlier in the dependency order)
- Forms updated next
- Workflow updated last
Troubleshooting
"Dependency not found" Error
If you see this error, it means:
- An item references something that doesn't exist in the target portal
- The referenced item wasn't included in your deployment selection
Solution: Include the missing dependency in your changeset, or ensure it already exists in the target portal.
Deployment Stuck on One Item
If a deployment seems stuck:
- The item might be waiting for a dependency to complete
- Check the deployment logs to see which item is currently processing
- Verify that all dependencies were successfully deployed
Items Deployed in Unexpected Order
The system always follows the standard dependency order. If items appear out of order:
- Check the item types - they might be in different categories
- Review the deployment logs to see the actual sequence
- Remember that within one type, creates run before updates and updates before deletes; inside one type and operation, items keep the order they appear in the changeset
Best Practices
Let the System Handle It
Trust the automatic dependency resolution. Don't try to manually order items or deploy them in separate batches unless you have a specific reason.
Include Complete Feature Sets
When deploying a new feature, include all related metadata in one changeset:
- The custom object and all its properties
- The pipeline and all its stages
- The forms, workflows, and lists that use them
This ensures everything is deployed in the correct order in a single operation.
Review Before Deploying
Before starting a deployment, review the changeset to ensure:
- All necessary items are included
- No critical dependencies are missing
- The scope makes sense as a complete unit
Related Features
- Pre-Deployment Backups - Automatic backups before deployment
- Deployment Strategies - How items are deployed (batch vs sequential)
- Assisted Deployment - Manual deployment with retry options