# VibeSharing Troubleshooting Guide

This guide is for both humans and Claude Code instances. When you hit an error, find the matching section below for the exact fix.

---

## MCP Setup Issues

### Token is placeholder / not set

**Symptom:** MCP commands fail with authentication errors, or token shows as `your-deploy-token`.

**Fix:** Get your real token from the dashboard and re-add the MCP server:

```bash
claude mcp add vibesharing -s user -e VIBESHARING_TOKEN=vs_YOUR_REAL_TOKEN -- npx -y @vibesharingapp/mcp-server
```

Get your token at: https://vibesharing.app/dashboard/account

### MCP scoped to wrong directory

**Symptom:** MCP tools only appear in one project, not globally.

**Fix:** Remove the project-scoped entry and re-add with `-s user`:

```bash
claude mcp remove vibesharing
claude mcp add vibesharing -s user -e VIBESHARING_TOKEN=vs_YOUR_TOKEN -- npx -y @vibesharingapp/mcp-server
```

The `-s user` flag makes the MCP server available in all projects, not just the current directory.

### MCP server not loading after restart

**Symptom:** Claude Code starts but VibeSharing tools are not available.

**Fix:** Check MCP status:

```
/mcp
```

If vibesharing is listed but shows an error, try removing and re-adding it. If it is not listed at all, add it:

```bash
claude mcp add vibesharing -s user -e VIBESHARING_TOKEN=vs_YOUR_TOKEN -- npx -y @vibesharingapp/mcp-server
```

### Token invalid or expired

**Symptom:** `"Unauthorized"` or `401` errors when using MCP tools.

**Fix:**
1. Go to https://vibesharing.app/dashboard/account
2. Regenerate your deploy token
3. Update the MCP server with the new token:

```bash
claude mcp remove vibesharing
claude mcp add vibesharing -s user -e VIBESHARING_TOKEN=vs_NEW_TOKEN -- npx -y @vibesharingapp/mcp-server
```

### Missing tools or old version (npx cache)

**Symptom:** MCP shows fewer tools than expected, or tools like `share_html`, `diagnose` are missing. Version shows as old (e.g., 0.3.x or 0.6.x).

**Cause:** npx caches packages locally and doesn't always pull the latest version.

**Best fix — switch to the remote server (no cache, always latest):**

For Cursor / Claude Desktop, update your MCP config to:

```json
{
  "mcpServers": {
    "vibesharing": {
      "url": "https://vibesharing.app/api/mcp",
      "headers": {
        "Authorization": "Bearer vs_YOUR_TOKEN"
      }
    }
  }
}
```

No npm, no npx, no cache. Always up to date.

**Alternative fix — clear the npx cache:**

```bash
npx clear-npx-cache
```

Then restart your editor. If that doesn't work:

```bash
rm -rf ~/.npm/_npx
```

**If you have a globally installed version:**

Check with `which vibesharing-mcp`. If it shows `/opt/homebrew/bin/vibesharing-mcp`, uninstall it:

```bash
npm uninstall -g @vibesharingapp/mcp-server
```

Then switch to the remote server config above.

---

## Deploy Failures

### "Another deploy is already in progress"

**Cause:** A previous deploy did not finish cleanly and the deploy lock is stuck.

**Fix:** Wait 2 minutes for the lock to expire automatically. If it persists, contact the admin using the `send_support_request` MCP tool or reach out through the dashboard.

### "Unauthorized" / 401

**Cause:** Deploy token is missing, invalid, or expired. Session may also have expired.

**Fix:**
1. Verify your token starts with `vs_`
2. Regenerate at https://vibesharing.app/dashboard/account
3. Update your config:

```bash
# For MCP:
claude mcp remove vibesharing
claude mcp add vibesharing -s user -e VIBESHARING_TOKEN=vs_NEW_TOKEN -- npx -y @vibesharingapp/mcp-server

# For CLI / deploy script:
mkdir -p ~/.vibesharing
echo '{"deployToken": "vs_NEW_TOKEN"}' > ~/.vibesharing/config.json
```

### Deploy times out

**Cause:** Large files or slow network. The deploy endpoint has a 120-second timeout (`maxDuration: 120`).

**Fix:**
1. Reduce project size — remove large assets, videos, unused dependencies
2. Make sure `node_modules`, `.git`, `.next`, and build artifacts are excluded
3. Retry the deploy — transient network issues resolve on retry

### "No Vercel token configured"

**Cause:** The organization admin has not added a Vercel token in the platform settings. This is an admin-level configuration.

**Fix:** Contact your organization admin and ask them to add a Vercel token in the VibeSharing admin settings. Individual users cannot fix this.

### 404 after deploy

**Cause:** The deployed project has no `index.html` at the root, or static HTML needs a redirect/rewrite rule.

**Fix:**
- For Next.js projects: make sure you have `app/page.tsx` or `pages/index.tsx`
- For static HTML: make sure `index.html` exists at the project root
- If using a framework with client-side routing, you may need a `vercel.json` with rewrites:

```json
{
  "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}
```

### "Access Required" on Vercel deployment URL

**Cause:** Vercel deployment protection is enabled on the prototype's Vercel project. This blocks public access.

**Fix:** This is an admin-level issue. Contact the VibeSharing admin and ask them to disable deployment protection for your prototype's Vercel project.

---

## GitHub Issues

### No GitHub repo created

**Cause:** Your GitHub account is not connected to VibeSharing.

**Fix:**
1. Go to https://vibesharing.app/dashboard/account
2. Click **Connect GitHub**
3. Authorize the VibeSharing GitHub OAuth app
4. Retry creating the repo / deploying

### Push permission denied

**Cause:** Your GitHub account is not connected, so VibeSharing cannot grant you push access to the prototype repo.

**Fix:** Connect GitHub at https://vibesharing.app/dashboard/account. After connecting, VibeSharing automatically adds your GitHub username as a collaborator on prototype repos you create.

### "Service account not configured"

**Cause:** The VibeSharing GitHub service account token is missing or invalid. This is a platform-level issue.

**Fix:** Contact the VibeSharing admin. Individual users cannot fix this.

---

## Collection / Prototype Issues

### Can't create collection

**Cause:** You may not be logged in, or you may not be a member of the organization.

**Fix:**
1. Confirm you are logged in at https://vibesharing.app/dashboard
2. Check that you are a member of the organization you are trying to create a collection in
3. If you just signed up, ask the org admin to add you as a member

### Can't add prototype to collection

**Cause:** Prototypes are not added directly to collections. You need to create a **Project** inside a collection first, then add a **Prototype** inside that project.

**Fix:**
1. Go to the collection
2. Click **New Project** to create a project inside it
3. Open the project, then click **Add Prototype**

### RLS policy violation

**Symptom:** Error message about row-level security, or error code `42501`, or "permission denied".

**Cause:** Your database permissions do not allow this operation. Usually means you are not a member of the organization that owns the resource.

**Fix:** Contact your organization admin and confirm your membership. If you believe this is a bug, use the `send_support_request` MCP tool with the exact error message.

---

## Getting Help

### Self-diagnosis

Use the `diagnose` MCP tool to automatically check your setup:
- Token validity
- GitHub connection status
- Organization membership
- MCP configuration

### Contact admin

Use the `send_support_request` MCP tool to send a message to the VibeSharing admin with full context about your issue. Include the exact error message.

### Dashboard links

- **Account settings (token, GitHub):** https://vibesharing.app/dashboard/account
- **Your prototypes:** https://vibesharing.app/dashboard
- **Create new prototype:** https://vibesharing.app/dashboard/new