Investigate a failure

A form can load correctly and still fail when someone submits it. We'll create that situation on a preview and use its runtime logs to find the cause. The published catalog will keep serving the working version.

Start from the released, clean production branch. Assuming its name is main, create the exercise branch:

git status
git switch main
git pull --ff-only
git switch -c form-recovery

Stay on form-recovery throughout this exercise. We'll use preview deployments and keep this deliberate failure out of the production branch.

Outcome

Find the cause of the preview form failure by matching its error message with the deployment's runtime log.

Hands-on exercise 5.3

Introduce one known failure

Open app/actions/interest.ts. Replace the existing apiKey property in its config object with this expression:

apiKey: process.env.VERCEL_ENV === "preview"
  ? undefined
  : process.env.RESEND_API_KEY,

This deliberately passes no key to the email helper on a Vercel preview. The other settings stay as they are. It doesn't delete or change a saved credential.

VERCEL_ENV is a Vercel system environment variable. Confirm automatic exposure of system variables is enabled in the project settings before relying on the condition. Its documented values include preview and production; see the system-variable reference. Local development won't normally have the preview value, so the failure is designed to appear on the deployed preview.

Review the one-file diff and save it separately:

git diff -- app/actions/interest.ts
git add app/actions/interest.ts
git diff --cached
git commit -m "test(interest): simulate missing email configuration on preview"
git rev-parse HEAD

Record the full identifier printed by the last command. This is the specific failure commit we will revert in 5.4. Don't mix a workshop edit or unrelated cleanup into it.

Deploy and identify the preview

Run vercel and wait for its preview deployment to succeed. Copy the returned deployment URL, then inspect that exact URL from the shell:

vercel inspect PASTE_PREVIEW_URL_HERE

Replace PASTE_PREVIEW_URL_HERE with the actual URL before running. Confirm the project and Preview environment before submitting anything.

The build can succeed because the pages still render. The error happens when the form calls the action, so we'll watch runtime logs while submitting. The inspect command identifies the deployment whose requests we'll follow with the log command.

Reproduce while watching logs

In a second shell terminal, follow logs for the same preview URL:

vercel logs PASTE_PREVIEW_URL_HERE --follow

Use the explicit URL so the command doesn't select another deployment. Leave it running, open that preview's gardening page, and submit valid test details once. The logs reference describes streaming runtime output.

The reference helper returns “The interest form isn't connected to email yet. Please try again later.” Its log event is interest.email_unconfigured. Match the request time with that event. The configured owner should receive no message from this attempt because the helper exits before calling Resend.

Check that the name, email, and question remain in the form after the failure. The pending button should become available again. This is the browser error-state check we deferred in 4.7.

Trace the event to code

Search the project for interest.email_unconfigured. It leads to lib/submit-interest.ts, where the helper checks required configuration. Follow its caller back to the config object we changed.

We can ask fx to explain this with a narrow prompt:

A valid inquiry on my preview displays the unconfigured-email
message. The runtime event is interest.email_unconfigured.
Inspect app/actions/interest.ts and lib/submit-interest.ts and
explain the path to that event. Do not read environment files,
change code, alter settings, send email, or deploy.

The explanation should identify our preview-only missing key. Compare it with the diff. We introduced the missing key ourselves. Following the log back to that edit gives us a process to use when the cause is less familiar.

Try It

Stop the log stream with Ctrl+C and write a short diagnosis in your course notes: the deployment URL, the visible form message, the runtime event, and the responsible commit identifier.

Open the stable production URL and confirm its three-workshop catalog still works. Check that the production deployment remains the release from 5.2. We haven't pushed or merged the exercise branch.

No runtime event appears

Check that the browser and log command use the same preview deployment. Submit valid fields so browser validation doesn't stop the request first. If the Firewall responds with 429, wait for its window; that blocked request won't reach the application logger.

The preview sends successfully

Recheck its source commit and the system-variable exposure setting. Confirm the uploaded action includes the preview condition. Don't simulate failure by removing a shared production credential. Correct the exercise branch or deployment selection, then redeploy its preview.

Commit

Keep the dedicated failure commit and its identifier. The working tree should be clean. We will create the correction in 5.4, preserving both the failure and recovery in the branch history.

Done-When

The intentional change is confined to form-recovery and a preview deployment.
A valid inquiry shows the unconfigured message and retains its entered values.
The matching runtime event leads back to the changed configuration expression.
The failure commit is recorded and production still uses the working release.

Solution

The temporary configuration in app/actions/interest.ts is:

const config = {
  apiKey: process.env.VERCEL_ENV === "preview"
    ? undefined
    : process.env.RESEND_API_KEY,
  from: process.env.INTEREST_FROM_EMAIL,
  to: process.env.INTEREST_TO_EMAIL,
};

All other code stays unchanged. On a configured Vercel preview, this edit passes no key to the helper. It logs interest.email_unconfigured and returns before sending. The next lesson removes this change with a targeted Git revert.