v3: better task metadata errors (#991)

* v3: better handle task metadata parse errors, and display nicely formatted errors (dev, deploy, UI)

* Add changeset

Author: ericallam

.changeset/breezy-gorillas-mate.md

@@ -0,0 +1,6 @@
+---
+"trigger.dev": patch
+"@trigger.dev/core": patch
+---
+
+better handle task metadata parse errors, and display nicely formatted errors

.vscode/launch.json

@@ -41,7 +41,7 @@
       "type": "node-terminal",
       "request": "launch",
       "name": "Debug V3 Deploy CLI",
-      "command": "pnpm exec trigger.dev deploy --skip-deploy",
+      "command": "pnpm exec trigger.dev deploy",
       "cwd": "${workspaceFolder}/references/v3-catalog",
       "sourceMaps": true
     },

apps/webapp/app/presenters/v3/DeploymentPresenter.server.ts

@@ -1,8 +1,15 @@
+import {
+  DeploymentErrorData,
+  TaskMetadataFailedToParseData,
+  groupTaskMetadataIssuesByTask,
+} from "@trigger.dev/core/v3";
 import { WorkerDeployment, WorkerDeploymentStatus } from "@trigger.dev/database";
+import { z } from "zod";
 import { PrismaClient, prisma } from "~/db.server";
 import { Organization } from "~/models/organization.server";
 import { Project } from "~/models/project.server";
 import { User } from "~/models/user.server";
+import { safeJsonParse } from "~/utils/json";
 import { getUsername } from "~/utils/username";
 
 export class DeploymentPresenter {
@@ -51,6 +58,7 @@ export class DeploymentPresenter {
         id: true,
         shortCode: true,
         version: true,
+        errorData: true,
         environment: {
           select: {
             id: true,
@@ -120,7 +128,81 @@ export class DeploymentPresenter {
           userName: getUsername(deployment.environment.orgMember?.user),
         },
         deployedBy: deployment.triggeredBy,
+        errorData: this.#prepareErrorData(deployment.errorData),
       },
     };
   }
+
+  #prepareErrorData(errorData: WorkerDeployment["errorData"]) {
+    if (!errorData) {
+      return;
+    }
+
+    const parsedErrorData = DeploymentErrorData.safeParse(errorData);
+
+    if (!parsedErrorData.success) {
+      return;
+    }
+
+    if (parsedErrorData.data.name === "TaskMetadataParseError") {
+      const errorJson = safeJsonParse(parsedErrorData.data.stack);
+
+      if (errorJson) {
+        const parsedError = TaskMetadataFailedToParseData.safeParse(errorJson);
+
+        if (parsedError.success) {
+          return {
+            name: parsedErrorData.data.name,
+            message: parsedErrorData.data.message,
+            stack: createTaskMetadataFailedErrorStack(parsedError.data),
+          };
+        } else {
+          return {
+            name: parsedErrorData.data.name,
+            message: parsedErrorData.data.message,
+          };
+        }
+      } else {
+        return {
+          name: parsedErrorData.data.name,
+          message: parsedErrorData.data.message,
+        };
+      }
+    }
+
+    return {
+      name: parsedErrorData.data.name,
+      message: parsedErrorData.data.message,
+      stack: parsedErrorData.data.stack,
+    };
+  }
+}
+
+function createTaskMetadataFailedErrorStack(
+  data: z.infer<typeof TaskMetadataFailedToParseData>
+): string {
+  const stack = [];
+
+  const groupedIssues = groupTaskMetadataIssuesByTask(data.tasks, data.zodIssues);
+
+  for (const key in groupedIssues) {
+    const taskWithIssues = groupedIssues[key];
+
+    if (!taskWithIssues) {
+      continue;
+    }
+
+    stack.push("\n");
+    stack.push(`  ❯ ${taskWithIssues.exportName} in ${taskWithIssues.filePath}`);
+
+    for (const issue of taskWithIssues.issues) {
+      if (issue.path) {
+        stack.push(`    x ${issue.path} ${issue.message}`);
+      } else {
+        stack.push(`    x ${issue.message}`);
+      }
+    }
+  }
+
+  return stack.join("\n");
 }

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.v3.$projectParam.deployments.$deploymentParam/route.tsx

@@ -3,6 +3,7 @@ import { LoaderFunctionArgs } from "@remix-run/server-runtime";
 import { typedjson, useTypedLoaderData } from "remix-typedjson";
 import { ExitIcon } from "~/assets/icons/ExitIcon";
 import { UserAvatar } from "~/components/UserProfilePhoto";
+import { CodeBlock } from "~/components/code/CodeBlock";
 import { EnvironmentLabel } from "~/components/environments/EnvironmentLabel";
 import { Badge } from "~/components/primitives/Badge";
 import { LinkButton } from "~/components/primitives/Buttons";
@@ -156,6 +157,26 @@ export default function Page() {
                 </TableBody>
               </Table>
             </div>
+          ) : deployment.errorData ? (
+            <div className="flex flex-col">
+              {deployment.errorData.stack ? (
+                <CodeBlock
+                  language="markdown"
+                  rowTitle={deployment.errorData.message}
+                  code={deployment.errorData.stack}
+                  maxLines={20}
+                />
+              ) : (
+                <div className="flex flex-col">
+                  <Paragraph
+                    variant="base/bright"
+                    className="w-full border-b border-grid-dimmed py-2.5"
+                  >
+                    {deployment.errorData.message}
+                  </Paragraph>
+                </div>
+              )}
+            </div>
           ) : null}
         </div>
       </div>

apps/webapp/app/utils/json.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 
-export function safeJsonParse(json: string): unknown {
+export function safeJsonParse(json?: string): unknown {
+  if (!json) {
+    return;
+  }
+
   try {
     return JSON.parse(json);
   } catch (e) {

apps/webapp/app/v3/services/createBackgroundWorker.server.ts

@@ -8,6 +8,7 @@ import { marqs, sanitizeQueueName } from "~/v3/marqs/index.server";
 import { calculateNextBuildVersion } from "../utils/calculateNextBuildVersion";
 import { BaseService } from "./baseService.server";
 import { projectPubSub } from "./projectPubSub.server";
+import { env } from "~/env.server";
 
 export class CreateBackgroundWorkerService extends BaseService {
   public async call(
@@ -110,7 +111,7 @@ export class CreateBackgroundWorkerService extends BaseService {
 export async function createBackgroundTasks(
   tasks: TaskResource[],
   worker: BackgroundWorker,
-  env: AuthenticatedEnvironment,
+  environment: AuthenticatedEnvironment,
   prisma: PrismaClientOrTransaction
 ) {
   for (const task of tasks) {
@@ -137,6 +138,18 @@ export async function createBackgroundTasks(
         queueName = sanitizeQueueName(`task/${task.id}`);
       }
 
+      const concurrencyLimit =
+        typeof task.queue?.concurrencyLimit === "number"
+          ? Math.max(
+              Math.min(
+                task.queue.concurrencyLimit,
+                environment.maximumConcurrencyLimit,
+                environment.organization.maximumConcurrencyLimit
+              ),
+              0
+            )
+          : null;
+
       const taskQueue = await prisma.taskQueue.upsert({
         where: {
           runtimeEnvironmentId_name: {
@@ -145,13 +158,13 @@ export async function createBackgroundTasks(
           },
         },
         update: {
-          concurrencyLimit: task.queue?.concurrencyLimit,
+          concurrencyLimit,
           rateLimit: task.queue?.rateLimit,
         },
         create: {
           friendlyId: generateFriendlyId("queue"),
           name: queueName,
-          concurrencyLimit: task.queue?.concurrencyLimit,
+          concurrencyLimit,
           runtimeEnvironmentId: worker.runtimeEnvironmentId,
           projectId: worker.projectId,
           rateLimit: task.queue?.rateLimit,
@@ -160,7 +173,11 @@ export async function createBackgroundTasks(
       });
 
       if (taskQueue.concurrencyLimit) {
-        await marqs?.updateQueueConcurrencyLimits(env, taskQueue.name, taskQueue.concurrencyLimit);
+        await marqs?.updateQueueConcurrencyLimits(
+          environment,
+          taskQueue.name,
+          taskQueue.concurrencyLimit
+        );
       }
     } catch (error) {
       if (error instanceof Prisma.PrismaClientKnownRequestError) {

packages/cli-v3/src/commands/deploy.ts

@@ -3,6 +3,7 @@ import { depot } from "@depot/cli";
 import { context, trace } from "@opentelemetry/api";
 import {
   ResolvedConfig,
+  TaskMetadataFailedToParseData,
   detectDependencyVersion,
   flattenAttributes,
   recordSpanException,
@@ -49,9 +50,11 @@ import { bundleDependenciesPlugin, workerSetupImportConfigPlugin } from "../util
 import { chalkError, chalkPurple, chalkWarning } from "../utilities/cliOutput";
 import {
   logESMRequireError,
+  logTaskMetadataParseError,
   parseBuildErrorStack,
   parseNpmInstallError,
 } from "../utilities/deployErrors";
+import { safeJsonParse } from "../utilities/safeJsonParse";
 
 const DeployCommandOptions = CommonCommandOptions.extend({
   skipTypecheck: z.boolean().default(false),
@@ -401,6 +404,24 @@ async function _deployCommand(dir: string, options: DeployCommandOptions) {
     }
     case "FAILED": {
       if (finishedDeployment.errorData) {
+        if (finishedDeployment.errorData.name === "TaskMetadataParseError") {
+          const errorJson = safeJsonParse(finishedDeployment.errorData.stack);
+
+          if (errorJson) {
+            const parsedError = TaskMetadataFailedToParseData.safeParse(errorJson);
+
+            if (parsedError.success) {
+              deploymentSpinner.stop(`Deployment encountered an error. ${deploymentLink}`);
+
+              logTaskMetadataParseError(parsedError.data.zodIssues, parsedError.data.tasks);
+
+              throw new SkipLoggingError(
+                `Deployment encountered an error: ${finishedDeployment.errorData.name}`
+              );
+            }
+          }
+        }
+
         const parsedError = finishedDeployment.errorData.stack
           ? parseBuildErrorStack(finishedDeployment.errorData)
           : finishedDeployment.errorData.message;

packages/cli-v3/src/commands/dev.tsx

@@ -38,11 +38,12 @@ import {
 import { logger } from "../utilities/logger.js";
 import { isLoggedIn } from "../utilities/session.js";
 import { createTaskFileImports, gatherTaskFiles } from "../utilities/taskFiles";
-import { UncaughtExceptionError } from "../workers/common/errors";
+import { TaskMetadataParseError, UncaughtExceptionError } from "../workers/common/errors";
 import { BackgroundWorker, BackgroundWorkerCoordinator } from "../workers/dev/backgroundWorker.js";
 import { runtimeCheck } from "../utilities/runtimeCheck";
 import {
   logESMRequireError,
+  logTaskMetadataParseError,
   parseBuildErrorStack,
   parseNpmInstallError,
 } from "../utilities/deployErrors";
@@ -548,7 +549,10 @@ function useDev({
                     backgroundWorker
                   );
                 } catch (e) {
-                  if (e instanceof UncaughtExceptionError) {
+                  if (e instanceof TaskMetadataParseError) {
+                    logTaskMetadataParseError(e.zodIssues, e.tasks);
+                    return;
+                  } else if (e instanceof UncaughtExceptionError) {
                     const parsedBuildError = parseBuildErrorStack(e.originalError);
 
                     if (typeof parsedBuildError !== "string") {

packages/cli-v3/src/utilities/deployErrors.ts

@@ -1,8 +1,11 @@
 import chalk from "chalk";
 import { relative } from "node:path";
-import { chalkError, chalkPurple, chalkGrey, chalkGreen } from "./cliOutput";
+import { chalkError, chalkPurple, chalkGrey, chalkGreen, chalkWarning } from "./cliOutput";
 import { logger } from "./logger";
 import { ReadConfigResult } from "./configFiles";
+import { TaskMetadataParseError } from "../workers/common/errors";
+import { z } from "zod";
+import { groupTaskMetadataIssuesByTask } from "@trigger.dev/core/v3";
 
 export type ESMRequireError = {
   type: "esm-require-error";
@@ -144,3 +147,35 @@ export function parseNpmInstallError(error: unknown): NpmInstallError {
 
   return "Unknown error";
 }
+
+export function logTaskMetadataParseError(zodIssues: z.ZodIssue[], tasks: any) {
+  logger.log(
+    `\n${chalkError("X Error:")} Failed to start. The following ${
+      zodIssues.length === 1 ? "task issue was" : "task issues were"
+    } found:`
+  );
+
+  const groupedIssues = groupTaskMetadataIssuesByTask(tasks, zodIssues);
+
+  for (const key in groupedIssues) {
+    const taskWithIssues = groupedIssues[key];
+
+    if (!taskWithIssues) {
+      continue;
+    }
+
+    logger.log(
+      `\n  ${chalkWarning("❯")} ${taskWithIssues.exportName} ${chalkGrey("in")} ${
+        taskWithIssues.filePath
+      }`
+    );
+
+    for (const issue of taskWithIssues.issues) {
+      if (issue.path) {
+        logger.log(`    ${chalkError("x")} ${issue.path} ${chalkGrey(issue.message)}`);
+      } else {
+        logger.log(`    ${chalkError("x")} ${chalkGrey(issue.message)}`);
+      }
+    }
+  }
+}

packages/cli-v3/src/utilities/safeJsonParse.ts

@@ -0,0 +1,11 @@
+export function safeJsonParse(json?: string): unknown {
+  if (!json) {
+    return undefined;
+  }
+
+  try {
+    return JSON.parse(json);
+  } catch {
+    return undefined;
+  }
+}

packages/cli-v3/src/workers/common/errors.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 export class UncaughtExceptionError extends Error {
   constructor(
     public readonly originalError: { name: string; message: string; stack?: string },
@@ -8,3 +10,14 @@ export class UncaughtExceptionError extends Error {
     this.name = "UncaughtExceptionError";
   }
 }
+
+export class TaskMetadataParseError extends Error {
+  constructor(
+    public readonly zodIssues: z.ZodIssue[],
+    public readonly tasks: any
+  ) {
+    super(`Failed to parse task metadata`);
+
+    this.name = "TaskMetadataParseError";
+  }
+}