fix: Handle registry sync validation errors and surface API error details in UI (#2389)

Author: daryllimyt

frontend/src/components/admin/admin-org-registry-table.tsx

@@ -15,6 +15,7 @@ import {
 } from "@/components/ui/dropdown-menu"
 import { toast } from "@/components/ui/use-toast"
 import { useAdminOrgRegistry } from "@/hooks/use-admin"
+import { getApiErrorDetail } from "@/lib/errors"
 import { getRelativeTime } from "@/lib/event-history"
 
 interface AdminOrgRegistryTableProps {
@@ -40,9 +41,12 @@ export function AdminOrgRegistryTable({
       })
     } catch (error) {
       console.error("Failed to sync repository", error)
+      const detail =
+        getApiErrorDetail(error) ??
+        "Failed to sync repository. Please try again."
       toast({
         title: "Sync failed",
-        description: "Failed to sync repository. Please try again.",
+        description: detail,
         variant: "destructive",
       })
     } finally {

frontend/src/components/admin/platform-registry-repos-table.tsx

@@ -19,6 +19,7 @@ import {
 } from "@/components/ui/dropdown-menu"
 import { toast } from "@/components/ui/use-toast"
 import { useAdminRegistryStatus, useAdminRegistrySync } from "@/hooks/use-admin"
+import { getApiErrorDetail } from "@/lib/errors"
 import { getRelativeTime } from "@/lib/event-history"
 
 export function PlatformRegistryReposTable() {
@@ -37,9 +38,12 @@ export function PlatformRegistryReposTable() {
       refetch()
     } catch (error) {
       console.error("Failed to sync repository", error)
+      const detail =
+        getApiErrorDetail(error) ??
+        "Failed to sync repository. Please try again."
       toast({
         title: "Sync failed",
-        description: "Failed to sync repository. Please try again.",
+        description: detail,
         variant: "destructive",
       })
     } finally {

frontend/src/lib/errors.test.ts

@@ -0,0 +1,43 @@
+import { getApiErrorDetail } from "@/lib/errors"
+
+describe("getApiErrorDetail", () => {
+  it("returns string detail when present", () => {
+    const error = Object.assign(new Error("Bad Request"), {
+      body: { detail: "Registry sync validation failed", message: null },
+    })
+
+    expect(getApiErrorDetail(error)).toBe("Registry sync validation failed")
+  })
+
+  it("prefers the API body message when detail is null", () => {
+    const error = Object.assign(new Error("Bad Request"), {
+      body: {
+        detail: null,
+        message: "Registry sync validation failed with 2 error(s).",
+      },
+    })
+
+    expect(getApiErrorDetail(error)).toBe(
+      "Registry sync validation failed with 2 error(s)."
+    )
+  })
+
+  it("serializes structured detail before falling back to the Error text", () => {
+    const error = Object.assign(new Error("Bad Request"), {
+      body: {
+        detail: {
+          action: "tracecat.examples.broken",
+          reason: "Action not found",
+        },
+        message: "Internal Server Error",
+      },
+    })
+
+    expect(getApiErrorDetail(error)).toBe(
+      JSON.stringify({
+        action: "tracecat.examples.broken",
+        reason: "Action not found",
+      })
+    )
+  })
+})

frontend/src/lib/errors.ts

@@ -2,7 +2,8 @@ import type { ApiError } from "@/client"
 
 export interface TracecatApiError<T = unknown> extends ApiError {
   readonly body: {
-    detail: T
+    detail?: T
+    message?: string | null
   }
 }
 
@@ -40,3 +41,27 @@ export function isRequestValidationErrorArray(
 ): obj is RequestValidationError[] {
   return Array.isArray(obj) && obj.every((o) => isRequestValidationError(o))
 }
+
+export function getApiErrorDetail(error: unknown): string | null {
+  if (!(error instanceof Error)) {
+    return null
+  }
+
+  const maybeApiError = error as TracecatApiError<unknown>
+  const detail = maybeApiError.body?.detail
+  if (typeof detail === "string") {
+    return detail
+  }
+  if (detail != null) {
+    try {
+      return JSON.stringify(detail)
+    } catch {
+      return error.message
+    }
+  }
+  const message = maybeApiError.body?.message
+  if (typeof message === "string" && message.length > 0) {
+    return message
+  }
+  return error.message
+}

tests/integration/test_install_and_run_custom_remote_registry_flow.py

@@ -37,6 +37,7 @@
 from tracecat.settings.schemas import GitSettingsUpdate
 
 GIT_SSH_URL = "git+ssh://git@github.com/TracecatHQ/internal-registry.git"
+KNOWN_GOOD_REMOTE_COMMIT_SHA = "e2bfd94c35c93f8052c2b97ff542961596ddd3f8"
 
 
 @pytest.mark.anyio
@@ -190,6 +191,7 @@ async def test_remote_custom_registry_repo() -> None:
     )
     sync_response = session.post(
         f"{base_url}/registry/repos/{repository_id}/sync",
+        json={"target_commit_sha": KNOWN_GOOD_REMOTE_COMMIT_SHA},
     )
     assert sync_response.status_code == 200, f"Sync failed: {sync_response.text}"
     sync_data = sync_response.json()

tests/unit/api/test_api_admin_tiers.py

@@ -9,6 +9,7 @@
 from fastapi.testclient import TestClient
 from tracecat_ee.admin.tiers import router as tiers_router
 
+from tracecat import config as tracecat_config
 from tracecat.auth.types import Role
 from tracecat.tiers.schemas import OrganizationTierRead, TierRead
 
@@ -81,7 +82,7 @@ async def test_list_org_tiers_success(
 async def test_create_tier_blocked_without_multi_tenant(
     client: TestClient, test_admin_role: Role, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    monkeypatch.setattr(tiers_router.config, "TRACECAT__EE_MULTI_TENANT", False)
+    monkeypatch.setattr(tracecat_config, "TRACECAT__EE_MULTI_TENANT", False)
 
     response = client.post(
         "/admin/tiers",
@@ -96,7 +97,7 @@ async def test_update_org_tier_blocked_without_multi_tenant(
     client: TestClient, test_admin_role: Role, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     org_id = uuid.uuid4()
-    monkeypatch.setattr(tiers_router.config, "TRACECAT__EE_MULTI_TENANT", False)
+    monkeypatch.setattr(tracecat_config, "TRACECAT__EE_MULTI_TENANT", False)
 
     response = client.patch(
         f"/admin/tiers/organizations/{org_id}",

tests/unit/test_registry_sync_base_service.py

@@ -5,6 +5,8 @@
 
 import pytest
 from sqlalchemy.ext.asyncio import AsyncSession
+from temporalio.client import WorkflowFailureError
+from temporalio.exceptions import ApplicationError
 
 from tracecat import config
 from tracecat.auth.types import Role
@@ -18,7 +20,8 @@
 from tracecat.registry.repositories.schemas import RegistryRepositoryCreate
 from tracecat.registry.repositories.service import RegistryReposService
 from tracecat.registry.sync.base_service import ArtifactsBuildResult
-from tracecat.registry.sync.service import RegistrySyncService
+from tracecat.registry.sync.runner import RegistrySyncValidationError
+from tracecat.registry.sync.service import RegistrySyncError, RegistrySyncService
 from tracecat.registry.versions.service import RegistryVersionsService
 
 
@@ -91,9 +94,15 @@ async def test_sync_creates_collision_version_for_manifest_changes(
     mocker.patch(
         "tracecat.registry.sync.base_service.fetch_actions_from_subprocess",
         side_effect=[
-            SimpleNamespace(actions=first_actions, commit_sha=None),
-            SimpleNamespace(actions=second_actions, commit_sha=None),
-            SimpleNamespace(actions=second_actions, commit_sha=None),
+            SimpleNamespace(
+                actions=first_actions, commit_sha=None, validation_errors={}
+            ),
+            SimpleNamespace(
+                actions=second_actions, commit_sha=None, validation_errors={}
+            ),
+            SimpleNamespace(
+                actions=second_actions, commit_sha=None, validation_errors={}
+            ),
         ],
     )
 
@@ -138,3 +147,67 @@ async def fake_build_and_upload_artifacts(
     versions_service = RegistryVersionsService(session, role)
     versions = await versions_service.list_versions(repository_id=repo.id)
     assert len(versions) == 2
+
+
+@pytest.mark.anyio
+async def test_sync_via_temporal_matches_validation_application_error_before_cause_walk(
+    session: AsyncSession,
+    mock_org_id: uuid.UUID,
+    mocker,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(config, "TRACECAT__REGISTRY_SYNC_SANDBOX_ENABLED", True)
+
+    session.add(
+        Organization(
+            id=mock_org_id,
+            name="Sync Test Org",
+            slug=f"sync-test-{mock_org_id.hex[:8]}",
+            is_active=True,
+        )
+    )
+    await session.flush()
+
+    role = Role(
+        type="service",
+        user_id=mock_org_id,
+        organization_id=mock_org_id,
+        workspace_id=uuid.uuid4(),
+        service_id="tracecat-runner",
+    )
+
+    repos_service = RegistryReposService(session, role)
+    repo = await repos_service.create_repository(
+        RegistryRepositoryCreate(origin=DEFAULT_REGISTRY_ORIGIN)
+    )
+
+    validation_error = RegistrySyncValidationError(
+        {
+            "tracecat.examples.broken": [],
+        }
+    )
+    try:
+        raise ApplicationError(
+            str(validation_error),
+            non_retryable=True,
+            type="RegistrySyncValidationError",
+        ) from validation_error
+    except ApplicationError as app_error:
+        workflow_error = WorkflowFailureError(cause=app_error)
+
+    mock_client = mocker.Mock()
+    mock_client.execute_workflow = mocker.AsyncMock(side_effect=workflow_error)
+    mocker.patch(
+        "tracecat.dsl.client.get_temporal_client",
+        mocker.AsyncMock(return_value=mock_client),
+    )
+
+    sync_service = RegistrySyncService(session, role)
+
+    with pytest.raises(
+        RegistrySyncError,
+        match="RegistrySyncValidationError: Registry sync validation failed",
+    ) as exc_info:
+        await sync_service.sync_repository_v2(repo, commit=False)
+
+    assert "workflow failed" not in str(exc_info.value).lower()