@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-common-errors/SKILL.md

@@ -1,109 +1,213 @@
 ---
 name: vercel-common-errors
-description: |
-  Diagnose and fix Vercel common errors and exceptions.
-  Use when encountering Vercel errors, debugging failed requests,
-  or troubleshooting integration issues.
+description: 'Diagnose and fix common Vercel deployment and function errors.
+
+  Use when encountering Vercel errors, debugging failed deployments,
+
+  or troubleshooting serverless function issues.
+
   Trigger with phrases like "vercel error", "fix vercel",
-  "vercel not working", "debug vercel".
-allowed-tools: Read, Grep, Bash(curl:*)
+
+  "vercel not working", "debug vercel", "vercel 500", "vercel build failed".
+
+  '
+allowed-tools: Read, Grep, Bash(vercel:*), Bash(curl:*)
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- debugging
+- errors
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Common Errors
 
 ## Overview
-Quick reference for the top 10 most common Vercel errors and their solutions.
+
+Diagnose and resolve the most common Vercel errors across three layers: build pipeline, serverless function runtime, and edge network. Each error includes the error code, root cause, and step-by-step fix.
 
 ## Prerequisites
-- Vercel SDK installed
-- API credentials configured
-- Access to error logs
+
+- Vercel CLI installed
+- Access to deployment logs (`vercel logs <url>`)
+- Access to Vercel dashboard for build logs
 
 ## Instructions
 
-### Step 1: Identify the Error
-Check error message and code in your logs or console.
+### Step 1: Identify the Error Layer
 
-### Step 2: Find Matching Error Below
-Match your error to one of the documented cases.
+```text
+# Check deployment status and error details
+vercel inspect <deployment-url>
 
-### Step 3: Apply Solution
-Follow the solution steps for your specific error.
+# View function runtime logs
+vercel logs <deployment-url> --follow
 
-## Output
-- Identified error cause
-- Applied fix
-- Verified resolution
+# View build logs via API
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v13/deployments/dpl_xxx" | jq '.state, .errorMessage'
+```
 
-## Error Handling
+**Three error layers:**
+
+1. **Build errors** — appear during `vercel deploy`, exit codes in build log
+2. **Runtime errors** — appear when functions are invoked, visible in function logs
+3. **Edge/routing errors** — HTTP errors from Vercel's edge network
+
+### Step 2: Build Errors
+
+**`BUILD_FAILED` — Build command exited with non-zero code**
 
-### Build Failed
-**Error Message:**
 ```
-Command 'npm run build' exited with 1
+Error: Command "npm run build" exited with 1
 ```
 
-**Cause:** Build script failed due to errors in code or dependencies
+- Check: `vercel.json` → `buildCommand` matches your build script
+- Check: all dependencies listed in `package.json` (not just devDependencies for runtime deps)
+- Fix: run `npm run build` locally to reproduce
+
+**`MISSING_BUILD_SCRIPT` — No build command found**
 
-**Solution:**
-```bash
-Check build logs in Vercel dashboard. Run 'npm run build' locally to reproduce.
+```
+Error: Missing Build Command
 ```
 
----
+- Fix: add `"build"` to `package.json` scripts or set `buildCommand` in vercel.json
+- For static sites: set `buildCommand` to empty string or `"true"`
+
+**`FUNCTION_PAYLOAD_TOO_LARGE` — Serverless function bundle > 250 MB**
 
-### Function Timeout
-**Error Message:**
 ```
-FUNCTION_INVOCATION_TIMEOUT
+Error: The Serverless Function "api/heavy" is 267 MB which exceeds the maximum size of 250 MB
 ```
 
-**Cause:** Serverless function exceeded execution time limit
+- Fix: add unused packages to `.vercelignore`, use dynamic imports, split into smaller functions
+- Check: `@vercel/nft` trace output to see what is being bundled
 
-**Solution:**
-Optimize function code, use Edge Runtime, or upgrade plan for longer timeouts.
+### Step 3: Runtime Errors
 
----
+**`FUNCTION_INVOCATION_FAILED` — Unhandled exception in function**
 
-### Domain Verification Failed
-**Error Message:**
-```
-Domain verification failed
+```bash
+# View the actual error
+vercel logs <deployment-url> --output=short
 ```
 
-**Cause:** DNS records not configured correctly
+- Common causes: undefined env var, missing database connection, unhandled promise rejection
+- Fix: wrap handler in try/catch, verify all env vars are set for the target environment
+
+**`FUNCTION_INVOCATION_TIMEOUT` — Function exceeded max duration**
+
+```
+Error: Task timed out after 10.00 seconds
+```
 
-**Solution:**
-```typescript
-Add required CNAME or A records. Wait for DNS propagation (up to 48h).
+- Hobby: 10s max, Pro: 60s default (up to 300s), Enterprise: 900s
+- Fix: optimize database queries, add connection pooling, or move to background processing
+- Configure in vercel.json:
+
+```json
+{
+  "functions": {
+    "api/slow-endpoint.ts": {
+      "maxDuration": 60
+    }
+  }
+}
 ```
 
-## Examples
+**`NO_RESPONSE_FROM_FUNCTION` — Function didn't return a response**
+
+- Cause: handler has a code path that doesn't call `res.send()`, `res.json()`, or return a Response
+- Fix: ensure ALL code paths return a response, including error handlers
+
+**`FUNCTION_THROTTLED` — Too many concurrent function invocations**
+
+- Hobby: 10 concurrent, Pro: 1000 concurrent
+- Fix: implement client-side retry with backoff, or upgrade plan
+
+### Step 4: Edge/Routing Errors
+
+**`404 NOT_FOUND`**
+
+- API route 404: verify file is in `api/` or `pages/api/` directory
+- Page 404: check `outputDirectory` in vercel.json, verify build output contains the file
+- Fix: run `vercel inspect <url>` to see the deployment file listing
+
+**`504 GATEWAY_TIMEOUT`**
+
+- Serverless function exceeded its timeout — same as FUNCTION_INVOCATION_TIMEOUT
+- Fix: increase `maxDuration` or optimize function
+
+**`413 REQUEST_ENTITY_TOO_LARGE`**
+
+- Request body exceeds 4.5 MB limit
+- Fix: use chunked upload, stream the body, or use presigned URLs for large files
+
+**`DEPLOYMENT_NOT_FOUND`**
+
+- Deployment was deleted or URL is malformed
+- Fix: verify the deployment still exists with `vercel ls`
+
+### Step 5: Environment Variable Errors
+
+**`ReferenceError: process is not defined` (Edge Runtime)**
+
+- Cause: using `process.env` in an edge function
+- Fix: Edge Functions can read env vars but only those defined at build time. Ensure vars are set.
+
+**Env var undefined in production but works in preview**
+
+- Cause: variable scoped to Preview only, not Production
+- Fix: check scopes in **Settings > Environment Variables**, add Production target
 
-### Quick Diagnostic Commands
 ```bash
-# Check Vercel status
-curl -s https://www.vercel-status.com
+# Check which environments have the variable
+vercel env ls | grep DATABASE_URL
+```
 
-# Verify API connectivity
-curl -I https://api.vercel.com
+## Quick Diagnosis Flowchart
 
-# Check local configuration
-env | grep VERCEL
+```
+Error occurred
+├── During build? → Check build logs, run `npm run build` locally
+├── During function invocation? → Check function logs with `vercel logs`
+├── HTTP 404? → Verify file exists in deployment: `vercel inspect`
+├── HTTP 500? → Unhandled exception in function code
+├── HTTP 504? → Function timeout — increase maxDuration
+└── HTTP 429? → Rate limited — implement retry with backoff
 ```
 
-### Escalation Path
-1. Collect evidence with `vercel-debug-bundle`
-2. Check Vercel status page
-3. Contact support with request ID
+## Output
+
+- Error layer identified (build, runtime, or edge)
+- Root cause diagnosed using logs and inspection
+- Fix applied and verified via new deployment
+- Prevention measures documented
+
+## Error Handling
+
+| Error Code | HTTP | Layer | Quick Fix |
+|-----------|------|-------|-----------|
+| `BUILD_FAILED` | — | Build | Run build locally, check deps |
+| `FUNCTION_INVOCATION_FAILED` | 500 | Runtime | Check env vars, add try/catch |
+| `FUNCTION_INVOCATION_TIMEOUT` | 504 | Runtime | Increase maxDuration in vercel.json |
+| `FUNCTION_THROTTLED` | 429 | Runtime | Reduce concurrency or upgrade plan |
+| `FUNCTION_PAYLOAD_TOO_LARGE` | 413 | Build | Reduce bundle size |
+| `NOT_FOUND` | 404 | Edge | Verify file paths and routes |
+| `EDGE_FUNCTION_INVOCATION_FAILED` | 500 | Edge | Remove Node.js APIs from edge code |
+| `NO_RESPONSE_FROM_FUNCTION` | 502 | Runtime | Return response from all code paths |
 
 ## Resources
-- [Vercel Status Page](https://www.vercel-status.com)
-- [Vercel Support](https://vercel.com/docs/support)
+
 - [Vercel Error Codes](https://vercel.com/docs/errors)
+- [Function Limitations](https://vercel.com/docs/functions/limitations)
+- [Platform Limits](https://vercel.com/docs/limits)
+- [Vercel Status Page](https://www.vercel-status.com)
+- [Vercel Logs CLI](https://vercel.com/docs/cli/logs)
 
 ## Next Steps
-For comprehensive debugging, see `vercel-debug-bundle`.
+
+For detailed debug bundles, see `vercel-debug-bundle`.

package/skills/vercel-common-errors/references/errors.md

@@ -0,0 +1,53 @@
+## Error Handling Reference
+
+### Build Failed
+
+**Error Message:**
+
+```
+Command 'npm run build' exited with 1
+```
+
+**Cause:** Build script failed due to errors in code or dependencies
+
+**Solution:**
+
+```bash
+Check build logs in Vercel dashboard. Run 'npm run build' locally to reproduce.
+```
+
+---
+
+### Function Timeout
+
+**Error Message:**
+
+```
+FUNCTION_INVOCATION_TIMEOUT
+```
+
+**Cause:** Serverless function exceeded execution time limit
+
+**Solution:**
+Optimize function code, use Edge Runtime, or upgrade plan for longer timeouts.
+
+---
+
+### Domain Verification Failed
+
+**Error Message:**
+
+```
+Domain verification failed
+```
+
+**Cause:** DNS records not configured correctly
+
+**Solution:**
+
+```typescript
+Add required CNAME or A records. Wait for DNS propagation (up to 48h).
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-common-errors/references/examples.md

@@ -0,0 +1,23 @@
+## Examples
+
+### Quick Diagnostic Commands
+
+```bash
+# Check Vercel status
+curl -s https://www.vercel-status.com
+
+# Verify API connectivity
+curl -I https://api.vercel.com
+
+# Check local configuration
+env | grep VERCEL
+```
+
+### Escalation Path
+
+1. Collect evidence with `vercel-debug-bundle`
+2. Check Vercel status page
+3. Contact support with request ID
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*