Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

fix(mcp): explain an untyped property rejection in the flag error (#120777)

Phil Haack8ee1baa012ad
diff --git a/products/feature_flags/backend/test/test_filters_validation.py b/products/feature_flags/backend/test/test_filters_validation.py
index 79326dc7d96a..6d08aacd0c19 100644
--- a/products/feature_flags/backend/test/test_filters_validation.py
+++ b/products/feature_flags/backend/test/test_filters_validation.py
@@ -373,6 +373,26 @@ class TestFiltersValidation(SimpleTestCase):
"services/mcp/tests/unit/preserve-group-targeting.test.ts, then this assertion."
)
+ @parameterized.expand([("serde_guard", set()), ("structural", {"*"})])
+ def test_property_type_rejection_detail_starts_with_the_property_path(
+ self, _name: str, enforced_rules: set[str]
+ ) -> None:
+ filters = {
+ "groups": [
+ {"properties": [], "rollout_percentage": 100},
+ {"properties": [{"key": "plan", "operator": "exact", "value": "pro"}], "rollout_percentage": 100},
+ ]
+ }
+ with override_settings(FEATURE_FLAG_FILTERS_ENFORCED_RULES=enforced_rules):
+ serializer = FeatureFlagSerializer(data={"filters": filters}, partial=True)
+ assert not serializer.is_valid()
+ assert str(serializer.errors["filters"][0]).startswith("groups[1].properties[0].type: "), (
+ "services/mcp/src/tools/featureFlags/updateFeatureFlagHooks.ts matches this prefix "
+ "(PROPERTY_TYPE_REJECTION) to add a recovery step to the update-feature-flag error. "
+ "If the prefix changes, update that regex and "
+ "services/mcp/tests/unit/update-feature-flag-preserving-groups.test.ts, then this assertion."
+ )
+
class TestRejectSerdeUnsafeFilters(SimpleTestCase):
# The only cache-poisoning guard that runs while the enforcement switch is off, and the
diff --git a/services/mcp/src/tools/featureFlags/updateFeatureFlagHooks.ts b/services/mcp/src/tools/featureFlags/updateFeatureFlagHooks.ts
index 006121b7c1a2..87e903b862ab 100644
--- a/services/mcp/src/tools/featureFlags/updateFeatureFlagHooks.ts
+++ b/services/mcp/src/tools/featureFlags/updateFeatureFlagHooks.ts
@@ -1,9 +1,12 @@
/**
* Hooks for the generated `update-feature-flag` tool. They intercept only `filters`, to
- * preserve group targeting (PostHog/posthog#46501), and leave everything else to the
- * generated handler. Re-sync is needed only if the `filters` param shape changes.
+ * preserve group targeting (PostHog/posthog#46501) and to explain a rejected property type,
+ * and leave everything else to the generated handler. Re-sync is needed if the `filters`
+ * param shape changes, or if the API changes the `groups[i].properties[j].type: ` prefix
+ * of its property type rejection.
*/
import type { Schemas } from '@/api/generated'
+import { PostHogValidationError } from '@/lib/errors'
import type { ToolHooks } from '@/tools/tool-hooks'
import type { Context } from '@/tools/types'
@@ -15,6 +18,10 @@ type UpdateParams = {
[key: string]: unknown
}
+// Matches both the API's serde guard ("invalid property type") and its structural tier
+// ("This field is required.", "... is not a valid choice."), which differ only after the path.
+const PROPERTY_TYPE_REJECTION = /^(groups\[(\d+)\]\.properties\[(\d+)\])\.type: /
+
async function beforeRequest<T extends UpdateParams>(context: Context, params: T): Promise<T> {
if (params.filters === undefined) {
return params
@@ -33,4 +40,40 @@ async function beforeRequest<T extends UpdateParams>(context: Context, params: T
return { ...params, filters: mergedFilters }
}
-export default { beforeRequest } satisfies ToolHooks<UpdateParams>
+// The API reports a rejected property type by path only. This adds the key from the sent filters
+// and the recovery step, whether `beforeRequest` left the type unset or the agent sent a bad one.
+// The rewrite keeps the PostHogValidationError class for two reasons. `handleToolError` returns
+// that class's message to the agent. Telemetry records only its code and attr, so the property
+// key stays out of analytics.
+function onError(_context: Context, params: UpdateParams, error: unknown): never {
+ if (!(error instanceof PostHogValidationError) || error.method !== 'PATCH' || error.attr !== 'filters') {
+ throw error
+ }
+ const match = PROPERTY_TYPE_REJECTION.exec(error.detail)
+ if (!match) {
+ throw error
+ }
+ const [, path, groupIndex, propertyIndex] = match
+ const key: unknown = params.filters?.groups?.[Number(groupIndex)]?.properties?.[Number(propertyIndex)]?.key
+ if (typeof key !== 'string') {
+ throw error
+ }
+ throw new PostHogValidationError({
+ ...error,
+ detail: `${error.detail}\n\n${propertyTypeRecoveryStep(`filters.${path}`, key)}`,
+ })
+}
+
+function propertyTypeRecoveryStep(path: string, key: string): string {
+ const quotedKey = JSON.stringify(key)
+ return (
+ `The property at ${path} (key ${quotedKey}) has a missing or invalid \`type\`. Read the flag. ` +
+ `If the flag already filters on ${quotedKey}, copy that filter's \`type\`, and its \`group_type_index\` ` +
+ `for a group property, from the stored condition you mean. ` +
+ `If that stored filter has no \`type\` either, ask the user which type to use. ` +
+ `Don't guess \`person\`: the API accepts it, and the condition then filters on a person property named ${quotedKey}. ` +
+ `If the flag doesn't filter on ${quotedKey} yet, set the \`type\` you mean, plus \`group_type_index\` for a group property.`
+ )
+}
+
+export default { beforeRequest, onError } satisfies ToolHooks<UpdateParams>
diff --git a/services/mcp/tests/unit/update-feature-flag-preserving-groups.test.ts b/services/mcp/tests/unit/update-feature-flag-preserving-groups.test.ts
index df59d1233b70..14333db18c6f 100644
--- a/services/mcp/tests/unit/update-feature-flag-preserving-groups.test.ts
+++ b/services/mcp/tests/unit/update-feature-flag-preserving-groups.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it, vi } from 'vitest'
+import { PostHogValidationError } from '@/lib/errors'
import { GENERATED_TOOLS } from '@/tools/generated/feature_flags'
import type { Context } from '@/tools/types'
@@ -131,4 +132,98 @@ describe('update-feature-flag preserving groups', () => {
expect(requestArgs(request, 0).method).toBe('PATCH')
expect(requestArgs(request, 0).body).toMatchObject({ active: false })
})
+
+ describe('untyped property error', () => {
+ const existing = {
+ id: 9,
+ key: 'pricing-banner',
+ filters: {
+ groups: [
+ {
+ properties: [{ key: 'country', type: 'person', operator: 'exact', value: 'US' }],
+ rollout_percentage: 100,
+ },
+ ],
+ },
+ }
+
+ // groups[0].properties[1] holds `email`, so a hook that swaps the group and property indices names the wrong key.
+ const params = tool.schema.parse({
+ id: 9,
+ filters: {
+ groups: [
+ {
+ properties: [
+ { key: 'country', type: 'person', operator: 'exact', value: 'US' },
+ { key: 'email', type: 'person', operator: 'exact', value: '[email protected]' },
+ ],
+ rollout_percentage: 100,
+ },
+ {
+ properties: [{ key: 'plan', operator: 'exact', value: 'pro' }],
+ rollout_percentage: 50,
+ },
+ ],
+ },
+ })
+
+ function rejectPatchWith(
+ detail: string,
+ code: string
+ ): { request: ReturnType<typeof vi.fn>; error: PostHogValidationError } {
+ const error = new PostHogValidationError({
+ detail,
+ attr: 'filters',
+ code,
+ extra: undefined,
+ url: 'https://us.posthog.com/api/projects/42/feature_flags/9/',
+ method: 'PATCH',
+ })
+ const request = vi.fn().mockResolvedValueOnce(existing).mockRejectedValueOnce(error)
+ return { request, error }
+ }
+
+ it.each([
+ {
+ shape: 'serde guard',
+ detail: 'groups[1].properties[0].type: invalid property type',
+ code: 'invalid',
+ },
+ {
+ shape: 'structural',
+ detail: 'groups[1].properties[0].type: This field is required.',
+ code: 'structural.groups[].properties[].type.required',
+ },
+ ])('names the rejected property and its fix for the $shape rejection', async ({ detail, code }) => {
+ const { request } = rejectPatchWith(detail, code)
+
+ const rejection: unknown = await tool.handler(createMockContext(request), params).catch((e: unknown) => e)
+
+ expect(rejection).toBeInstanceOf(PostHogValidationError)
+ expect(rejection).toMatchObject({ attr: 'filters', code, method: 'PATCH' })
+ const { message } = rejection as PostHogValidationError
+ expect(message).toContain(detail)
+ expect(message).toContain('filters.groups[1].properties[0]')
+ expect(message).toContain('"plan"')
+ expect(message).toContain("Don't guess `person`")
+ expect(message).not.toContain('"email"')
+ })
+
+ it.each([
+ {
+ scenario: 'a different field under filters',
+ detail: 'groups[0].properties[0].operator: "foo" is not a valid choice.',
+ code: 'structural.groups[].properties[].operator.invalid_choice',
+ },
+ {
+ scenario: 'a type path the sent filters do not contain',
+ detail: 'groups[5].properties[0].type: invalid property type',
+ code: 'invalid',
+ },
+ ])('rethrows the API error unchanged for $scenario', async ({ detail, code }) => {
+ const { request, error } = rejectPatchWith(detail, code)
+
+ await expect(tool.handler(createMockContext(request), params)).rejects.toBe(error)
+ })
+ })
})