Vercel Deploy Debug

Overview

This skill provides a systematic workflow for debugging Vercel deployment issues specific to the CoinSite project (Astro 5 with SSR, @astrojs/vercel adapter, Astro DB with Turso).

CRITICAL: Deployment Method

GitHub auto-deploys to Vercel on every git push. Each push = one deployment.

NEVER use manual Vercel CLI deploys:

# WRONG - Creates duplicate deployments
vercel deploy --prod
vercel --prod

Minimize deployments with this workflow:

The bd git hooks automatically flush beads changes to JSONL on git commit, so you don't need separate bd sync calls.

Optimized single-deployment workflow:

# 1. Work on the issue (claim, code, close)
bd update <id> --status=in_progress
# ... make code changes ...
bd close <id>

# 2. Stage EVERYTHING (code + beads) in one commit
git add -A
git commit -m "Your message"

# 3. ONE push = ONE deployment
git push

Why this works:

• bd update and bd close modify the local database
• The pre-commit hook flushes these to .beads/issues.jsonl
• git add -A stages both code AND beads changes
• Single git push triggers exactly one Vercel deployment

Avoid these patterns (cause multiple deployments):

# BAD: Calling bd sync separately pushes to git
bd sync  # <-- This pushes, triggering a deployment!
git push # <-- This ALSO pushes, another deployment!

# BAD: Multiple commits with pushes between
git commit && git push  # deployment 1
bd sync                 # deployment 2

End-of-session checklist:

git status                    # Check what changed
bd close <ids>                # Close completed issues
git add -A                    # Stage everything
git commit -m "..."           # Commit (hooks flush beads)
git push                      # ONE deployment

When To Use This Skill

• After pushing changes to GitHub when deployment fails
• When the deployed site shows 500 errors or unexpected behavior
• When Vercel build logs show errors
• To verify deployment status and configuration

Automated Health Check

Run the comprehensive health check script to automatically:

1. Fetch the latest Vercel deployment
2. Check deployment status (Ready/Error/Building)
3. Scan build logs for errors
4. Scan runtime logs for errors
5. Test key pages on lordmarcovan.com for HTTP errors

npx tsx .claude/skills/vercel-deploy-debug/scripts/deployment-health-check.ts

Optionally pass a specific deployment URL:

npx tsx .claude/skills/vercel-deploy-debug/scripts/deployment-health-check.ts https://coinsite-xxx.vercel.app

Manual Diagnostic Workflow

Step 1: Check Deployment Status

List recent deployments to see current state:

vercel ls

This shows deployment URLs, status (Ready, Error, Building), and timestamps.

Step 2: Inspect Specific Deployment

Get detailed info about a deployment:

vercel inspect <deployment-url>

Shows build output, function regions, and configuration details.

Step 3: View Build/Runtime Logs

Check logs for a specific deployment:

vercel logs <deployment-url>

Add --follow to stream logs in real-time during builds.

Step 4: Check Environment Variables

Verify environment variables are set correctly:

vercel env ls

For Astro DB with Turso, ensure these are set in Vercel:

• ASTRO_DB_REMOTE_URL - Turso database URL
• ASTRO_DB_APP_TOKEN - Turso auth token

Common Errors and Solutions

NoAdapterInstalled Error

Symptom: Build fails with "NoAdapterInstalled" or adapter not found.

Causes:

1. astro.config.mjs is gitignored and not deployed
2. Wrong import path for adapter version

Diagnostic:

# Check if astro.config.mjs is tracked
git ls-files astro.config.mjs

# Check .gitignore for problematic patterns
grep -E "^\*\.mjs|astro" .gitignore

Fix:

• Ensure astro.config.mjs is NOT in .gitignore
• For @astrojs/vercel v8.x, use: import vercel from '@astrojs/vercel/serverless'
• For @astrojs/vercel v9.x, use: import vercel from '@astrojs/vercel'

libsql Native Module Error

Symptom: Runtime 500 errors with "Could not locate libsql native module".

Cause: Deploying prebuilt output from macOS to Vercel's Linux environment.

Fix: Always use Vercel's remote build (default). Do NOT use:

# WRONG - builds locally then deploys
vercel build --prod && vercel deploy --prebuilt

Instead push to GitHub and let Vercel build remotely.

Cached Prebuilt Artifacts

Symptom: Vercel uses old prebuilt output instead of building fresh.

Diagnostic:

vercel inspect <url>
# Look for "Using prebuilt output" in logs

Fix:

1. Delete .vercel/output directory locally
2. In Vercel dashboard: Settings > Git > "Clear Build Cache & Redeploy"
3. Or set environment variable: VERCEL_FORCE_NO_BUILD_CACHE=1

SSL Certificate Issues

Symptom: Some browsers show certificate errors or different issuer.

Diagnostic:

# Check certificate chain
curl -v https://your-domain.vercel.app 2>&1 | grep -A 5 "SSL certificate"

# Detailed SSL check
openssl s_client -connect your-domain.vercel.app:443 -servername your-domain.vercel.app </dev/null 2>/dev/null | openssl x509 -noout -issuer -subject

Note: Vercel uses Let's Encrypt certificates. If you see a different issuer (e.g., NordVPN), it's client-side TLS interception by VPN/security software, not a server issue.

Project-Specific Configuration

Current Setup (CoinSite)

• Framework: Astro 5 with SSR (output: 'server')
• Adapter: @astrojs/vercel v8.2.7 (use /serverless import)
• Database: Astro DB with Turso (requires --remote flag for builds)
• Build command: astro build --remote

astro.config.mjs Template

import db from '@astrojs/db';
import vercel from '@astrojs/vercel/serverless';  // v8.x path
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'server',
  adapter: vercel(),
  integrations: [db()],
});

Quick Reference

Command	Purpose
npx tsx ...health-check.ts	Run automated health check
vercel ls	List deployments
vercel inspect <url>	Deployment details
vercel logs <url>	View logs
vercel env ls	List env vars
vercel env pull	Pull env vars to local .env
git push	Deploy to production (auto-triggers Vercel)

Resources

• scripts/deployment-health-check.ts - Automated health check script
• references/common-errors.md - Detailed error messages and stack traces