Common Issues and Solutions

Preview Deployment Protection

Problem: When Deployment Protection setting is enabled on Vercel, it's not possible to trigger and complete a workflow run on a preview deployment.

Solution: Vercel provides a way to bypass this protection by using a bypass secret. To create one, follow these steps:

1

Settings

Go to Deployment Protection section under your Vercel project settings.

2

Find related section

Click on Add Secret under Protection Bypass for Automation section.

3

Generate a bypass token

Don't forget to save it and store it as an environment variable (e.g., VERCEL_AUTOMATION_BYPASS_SECRET).

Now that you have a bypass token, you need to pass it as a header in two places to bypass deployment protection.

Using the Bypass Secret

Step 1: Configure QStash Client with Headers

Configure the QStash client with the bypass header in your workflow serve options. This ensures that all workflow steps, including context.invoke calls, will include the bypass header automatically:

import { Client } from '@upstash/qstash'import { serve } from '@upstash/workflow/nextjs'export const { POST } = serve<string>(async (context) => {  // your workflow logic}, {  qstashClient: new Client({    token: process.env.QSTASH_TOKEN!,    headers: {      "x-vercel-protection-bypass": process.env.VERCEL_AUTOMATION_BYPASS_SECRET!    }  })})

Step 2: Pass Header When Triggering

When triggering the workflow using curl or client.trigger, you must also pass the bypass secret as a header:

import { Client } from "@upstash/workflow";const client = new Client({ token: "<QSTASH_TOKEN>" })await client.trigger({  url: "https://vercel-preview.com/workflow",  headers: {    "x-vercel-protection-bypass": process.env.VERCEL_AUTOMATION_BYPASS_SECRET!  },  body: "Hello world!"})

curl -X POST \  'https://vercel-preview.com/workflow' \  -H 'x-vercel-protection-bypass: <PROTECTION_BYPASS_SECRET>' \  -d 'Hello world!'