Troubleshooting & Help
Find your issue below, or paste any section into an AI assistant for guided help.
Common Symptoms
Start here — find what you're experiencing and get a quick answer.
“I deployed my prototype but the URL is a 404”
Vercel may still be building, or Deployment Protection (SSO) is blocking public access. Check Vercel → Project Settings → Deployment Protection and disable it. If the URL looks truncated, check the Vercel dashboard for the actual alias — long project names get shortened.
“I uploaded my prototype but nothing shows up”
If you uploaded via ZIP and it seems to vanish, the server may be missing the SUPABASE_SERVICE_ROLE_KEY environment variable. Ask your admin to check. If you pasted an external URL, make sure it's publicly accessible (not behind a login).
“I clicked Deploy and got an error about tokens”
You need a deploy token that starts with vs_. Find yours in Dashboard → Settings → Deploy Tokens. If you're using the CLI, pass it with --token or set the VIBESHARING_TOKEN environment variable.
“I can log in but I can't see any projects”
You need to be a member of the organization. Ask the person who invited you to confirm your account was added. Access is controlled at the org level.
“I connected GitHub but it says 'not configured'”
There are two GitHub connections: yours (OAuth, via Dashboard → Settings → GitHub) and the server's (GITHUB_SERVICE_TOKEN, set by an admin). The 'not configured' message usually means the admin hasn't set the service token yet.
“My prototype deployed but changes aren't showing up”
Make sure you're deploying to the right prototype — check the prototype ID in .vibesharing/config.json matches what's in your dashboard URL. Also try a hard refresh (Cmd+Shift+R) to clear cached assets.
“I'm getting rate-limited by GitHub”
Without a token, GitHub only allows 60 API requests per hour. Set GITHUB_TOKEN in your environment to a personal access token and the limit jumps to 5,000/hr.
“My corporate network blocks ZIP uploads”
Some firewalls block file uploads to external services. Use the GitHub integration to deploy instead, or use the External URL feature to link to a prototype hosted elsewhere (Lovable, v0, internal server, etc.).
Detailed Reference
Deeper dives into specific systems — mostly for admins and CLI users.
🔑Deploy Tokens
What is a deploy token and where do I find it?
A deploy token authenticates your CLI or CI pipeline with VibeSharing. Find it in your project's Dashboard → Settings → Deploy Tokens. Each token is scoped to one prototype.
"Invalid deploy token" / "Unauthorized" errors
Make sure your token starts with vs_. Tokens that don't match this format are either expired or copied incorrectly. Regenerate from Dashboard → Settings → Deploy Tokens.
Token format — must start with vs_
All valid deploy tokens begin with the prefix vs_. If yours doesn't, you may be using an older token or a different credential (e.g. a Vercel token). Generate a fresh one from the dashboard.
CLI can't find token
The CLI resolves tokens in this priority order: --token flag → VIBESHARING_TOKEN environment variable → ~/.vibesharing/token file. Verify the value at the highest-priority source you're using.
▲Vercel & Deployment
"No Vercel token configured"
An admin needs to set the VERCEL_TOKEN environment variable in the VibeSharing server environment (or .env). This is a Vercel personal access token with deploy permissions.
Prototype deploys but URL doesn't load
Vercel Deployment Protection (SSO) may still be enabled on the project. Go to Vercel → Project Settings → Deployment Protection and disable it, or allowlist the public.
URL looks wrong / truncated
Vercel truncates long project names when generating aliases. VibeSharing polls for the actual alias but this can time out. Check the Vercel dashboard for the real URL, or shorten the prototype name.
Webhook not triggering redeployment
Redeployment webhooks must be configured manually in Vercel Project Settings → Git → Deploy Hooks. Create a hook and paste the URL into VibeSharing's prototype settings.
🐙GitHub & Git
"GitHub not connected"
Authorize VibeSharing via OAuth: go to Dashboard → Settings → Integrations → GitHub and click Connect. You'll be redirected to GitHub to grant access.
"Service account not configured"
The GITHUB_SERVICE_TOKEN environment variable is missing from the server. An admin needs to create a GitHub personal access token (with repo scope) and set it in the environment.
"API rate limit exceeded"
Without authentication GitHub allows only 60 requests/hour. Set the GITHUB_TOKEN environment variable to a personal access token to increase the limit to 5,000 requests/hour.
"No source code available" when initializing Git
This prototype was added via URL — no source code was uploaded. Upload your code first (ZIP or paste), then initialize the Git repo.
⌨️CLI
"No prototype ID provided"
Run: vibesharing init --prototype <id>. You can find the prototype ID in the dashboard URL or in the prototype's settings page.
"No files found to deploy"
The CLI looks for *.tsx, *.ts, *.css, *.json files in the ./app directory by default. If your files are elsewhere, use the --dir flag: vibesharing deploy --dir ./src.
Deploy succeeds but nothing changes
Verify the prototype ID in your config matches the one in the dashboard. You may be deploying to a different prototype. Check .vibesharing/config.json or run vibesharing status.
🔒Auth & Permissions
Can't see projects or folders
You must be a member of the organization. Access is enforced via Supabase Row Level Security (RLS). Ask your org admin to add your account.
"Session expired" during GitHub OAuth
Your VibeSharing session timed out while you were on GitHub. Log in again to VibeSharing, then retry the GitHub authorization flow.
Uploaded source not appearing
The server may be missing the SUPABASE_SERVICE_ROLE_KEY environment variable. Without it, server-side writes to the source table silently fail. An admin needs to set this key.
🏢Corporate & Network
ZIP upload blocked by corporate firewall
Deploy via GitHub integration instead, or add the prototype using the External URL feature which only requires the URL itself to be reachable.
Can't access vibesharing.app
Ask your IT department to allowlist vibesharing.app and *.vercel.app domains. Both are needed for the dashboard and deployed prototypes.
Using internal / on-prem hosting
If your prototype is hosted internally, use the External URL feature to add it to VibeSharing. VibeSharing will link to it without requiring deployment.
Still stuck?
We're happy to help. Reach out and we'll get back to you.