docs: update group documentation with validation troubleshooting guide

Author: pmallol

site/content/docs/cli/constructs-reference.md

@@ -474,7 +474,7 @@ Use the CheckGroupV2 construct to organize your Checks into groups. This comes w
 
 > Note: you will notice that managing shared configuration between Checks is very easy just using JS/TS. You might not need Check Groups for that purpose.
 
-#### Adding Checks to a Check Group
+### Adding Checks to a Check Group
 
 You can add a Check to a group in two ways.
 
@@ -533,6 +533,12 @@ new ApiCheck('check-group-api-check-1', {
 > Note that you can configure two different `frequency` properties for API and Browser checks in a `CheckGroup` separately.
 > The CLI follows a fallback logic using `Check->CheckGroup->Project` configurations.
 
+### Troubleshooting validation
+
+Group validation ensures that all checks within a group can support the selected configuration settings. Since uptime monitors and synthetic checks have different feature limitations based on your plan tier, Checkly validates group settings against the lowest common denominator of supported features to prevent configuration conflicts.
+
+For detailed troubleshooting guidance, see [Troubleshoot validation of Group](/docs/groups/troubleshoot/).
+
 ## `CheckGroup` (deprecated)
 
 As of CLI release v6.0 the CheckGroup construct is deprecated and will be removed in a future version. We recommend migrating to [CheckGroupV2](#checkgroupv2), which offers more intuitive behavior and better control.

site/content/docs/groups/_index.md

@@ -17,7 +17,7 @@ Groups help you organize your checks (e.g. by team or feature) and apply shared
 
 ![Check group screenshot](/docs/images/groups/group-in-dashboard.png)
 
-# Creating a check group
+## Creating a check group
 
 By default, newly created check groups behave like folders, with no [group-level configuration](#group-level-configuration) applied. To get started:
 
@@ -27,14 +27,16 @@ By default, newly created check groups behave like folders, with no [group-level
 
 You can populate a group by moving existing checks into it or by creating new checks directly within the group.
 
-# Group level configuration
+## Group level configuration
 
 Groups let you apply shared configuration to standardize how checks behave. Below is a breakdown of each setting and how it affects checks in the group:
 
 ### API checks defaults
+
 You can define [API check defaults](/docs/groups/api-check-defaults/) such as a common base URL, request information, [assertions](/docs/api-checks/assertions/), and [setup & teardown scripts](/docs/api-checks/setup-teardown-scripts/) to manage API checks in your group at scale.
 
 ### Variables
+
 For configuration information commonly used by checks in your group, create [group environment variables and secrets](/docs/groups/variables/). These are merged with variables at the global and check levels when a check runs.
 
 ### Scheduling & locations overrides
@@ -62,7 +64,7 @@ You can run checks in this group as [E2E tests](/docs/testing) locally or from y
 
 Checkly manages the [runtime](/docs/runtimes) environment for your JavaScript code in browser checks and setup & teardown scripts. If the checks in this group need a runtime different from your account default, you can set that here.
 
-# Adding or removing checks from groups
+## Adding or removing checks from groups
 
 * **Moving a check into a group:** If the group has [group-level configuration](#group-level-configuration) defined, adding a check may change how it runs. Settings like API defaults, locations & scheduling, or retries & alerting can override or append to the check’s configuration.
 
@@ -71,7 +73,7 @@ Checkly manages the [runtime](/docs/runtimes) environment for your JavaScript co
 > [!WARNING]
 > To prevent issues (e.g. broken references to group variables), the check will be automatically deactivated after being added to or removed from a group. Make sure to review its settings before reactivating.
 
-# How we run grouped checks
+## How we run grouped checks
 
 It helps to understand how we run the checks in a group, specifically if you're doing more sophisticated checks with shared
 variables, script and alerting channels. Here are the rules:
@@ -82,5 +84,10 @@ variables, script and alerting channels. Here are the rules:
 4. There are no results or metrics collected at the group level.
 5. Checks in a group still have their individual scheduling settings.
 
-As you can see, groups in their current incarnation are mostly handy configuration buckets for common properties. In the 
-future we will expand the group features to make them smarter.
+As you can see, groups in their current incarnation are mostly handy configuration buckets for common properties. In the future we will expand the group features to make them smarter.
+
+## Troubleshoot validation
+
+Group validation ensures that all checks within a group can support the selected configuration settings. Since uptime monitors and synthetic checks have different feature limitations based on your plan tier, Checkly validates group settings against the lowest common denominator of supported features to prevent configuration conflicts.
+
+Learn how to [resolve validation errors](/docs/groups/troubleshoot/) when configuring Groups with mixed check types.

site/content/docs/groups/troubleshoot.md

@@ -0,0 +1,123 @@
+---
+title: Troubleshoot validation of Group - Checkly Docs
+displayTitle: Troubleshoot validation of Group
+navTitle: Troubleshoot
+weight: 30
+menu:
+  resources:
+    parent: "Groups"
+    identifier: troubleshoot-groups
+
+---
+
+Groups in Checkly allow you to apply shared settings like API check defaults, scheduling strategy, locations, retries, and alerting across multiple checks. However, uptime monitors (TCP, URL, HTTP) and synthetic checks (Browser, API, Multi-step) don't always support the same features, which can lead to validation errors when mixing check types or using certain configurations on specific [plan tiers](https://www.checklyhq.com/pricing/).
+
+## Understanding Group Validation Rules
+
+When configuring groups, Checkly validates that all checks within the group can support the selected settings. The validation rules depend on your plan tier and the types of checks in your group.
+
+### Group Types and Validation
+
+**Synthetic-only groups:** All group overrides are available (same functionality as today).
+
+**Monitor-only groups:** Overrides are limited by your plan type. For example, only round-robin scheduling and limited retry options may be available.
+
+**Mixed groups (Synthetics & Monitors):** Only monitor overrides are allowed (lowest common denominator).
+
+> [!WARNING]
+> By default, all overrides are shown if a group is created without any checks.
+>
+> If you set scheduling or retry overrides before adding checks, this initializes the group as either synthetic-only or monitor-only. If features like parallel runs or advanced retries are selected, monitors cannot be added to the group.
+
+## Affected Properties by Plan Tier
+
+The following table shows which group properties are supported by different check types across plan tiers:
+
+| Group Property | Check Type | Hobby | Starter | Team | Enterprise |
+|---|---|---|---|---|---|
+| **Scheduling Strategy** | *Uptime* | Round robin | Round robin | Round robin | Round robin & Parallel |
+| | *Synthetics* | Round robin & Parallel | Round robin & Parallel | Round robin & Parallel | Round robin & Parallel |
+| **Retries** | *Uptime* | No retries | No retries | 1 retry | Full retries |
+| | *Synthetics* | Full retries | Full retries | Full retries | Full retries |
+| **Locations** | *Uptime* | 4 locations | 4 locations | 22 locations | 22 locations |
+| | *Synthetics* | 4 locations | 4 locations | 22 locations | 22 locations |
+| **Private Locations** | *Uptime* | No | No | Yes | Yes |
+| | *Synthetics* | No | No | Yes | Yes |
+| **Setup & Teardown** | *Uptime (HTTP)* | No | No | No | No |
+| | *Synthetics (API)* | Yes | Yes | Yes | Yes |
+
+## Common Validation Errors
+
+### Scheduling Strategy Conflicts
+
+**Error:** "Parallel scheduling is not supported for uptime monitors on your current plan."
+
+**Solution:**
+
+- If your group contains uptime monitors and you're on a Hobby, Starter, or Team plan, change the scheduling strategy to "Round robin"
+- Alternatively, separate uptime monitors into a different group
+- Upgrade to Enterprise plan
+
+### Retry Configuration Conflicts
+
+**Error:** "Advanced retry settings are not supported for uptime monitors on your current plan."
+
+**Solution:**
+
+- On Hobby and Starter plans: Remove retry configuration for groups containing uptime monitors
+- On Team plans: Limit retries to 1 for groups containing uptime monitors
+- Alternatively, separate uptime monitors into a different group
+- Upgrade to Enterprise plan
+
+### Location and Private Location Restrictions
+
+**Error:** "Some of the selected locations are not available on your current plan."
+
+**Solution:**
+
+- Ensure you're only using locations available on your plan tier
+- Upgrade to Team or Enterprise plan
+
+**Error:** "Private locations are not supported on your current plan."
+
+**Solution:**
+
+- Upgrade to Team or Enterprise plan
+
+## Resolving Validation Errors
+
+### For New Groups
+
+When creating a new group, validation occurs in real-time. If you encounter errors:
+
+1. [**Check your plan tier**](https://app.checklyhq.com/settings/account/billing) and review the [supported features table](/docs/groups/troubleshoot/#affected-properties-by-plan-tier) above
+2. **Consider the check types** you plan to add to the group
+3. **Adjust group settings** to match the lowest common denominator of supported features
+4. **Separate check types** into different groups if you need advanced features for synthetic checks
+
+### For Existing Groups
+
+Existing groups that have invalid rules will show errors when you attempt to save changes. To resolve these issues:
+
+1. **Review the specific error message** to identify the conflicting setting
+2. **Update group configuration** to use only supported features for your plan and check types
+3. **Move checks to separate groups** if you need different configurations for different check types
+
+> [!WARNING]
+> When downgrading your plan (e.g., from Team to Starter), existing groups with advanced features will show validation errors. You'll need to update the group configuration to match your new plan's limitations before you can save any changes.
+
+## API Check Defaults
+
+API check defaults defined at the group level (including request config, assertions, and setup/teardown scripts) are only applied to API checks within the group. These settings don't apply to URL monitors, even if some properties like base URL or status code assertions could technically be used.
+
+If you need similar defaults for URL monitors, consider creating separate groups or configure these settings individually at the check level.
+
+## Best Practices
+
+To avoid validation issues:
+
+- **Plan your group structure** based on check types and required features
+- **Use separate groups** for uptime monitors and synthetic checks if you need advanced features
+- **Start with basic configurations** and add advanced features only when all checks in the group support them
+- **Review plan limitations** before configuring group overrides
+- **Test group settings** with a single check before adding multiple checks to the group