Troubleshooting
Missing secrets, failed builds, Web 502s, Discord offline, GitHub import, and hosting.
Troubleshooting
Common issues for buyers and developers. For full workflows see Buyer workflow and Developer workflow.
| Symptom | What to try |
|---|---|
| Deploy blocked / missing required secrets | Buyer: set every key under Production secrets that the developer declared. Developer: only declare keys your code reads. |
| Build or validation failed | Developer: fix layout rules (Delivery format), then resubmit a ZIP or GitHub snapshot, or use Retry deploy / Rebuild on the project page. |
| Web public URL returns 502 | App must listen on 0.0.0.0 using env PORT (Velcio sets 8080). Wrong bind/port is the usual cause. See Web delivery format. |
Web /healthz returns 404 | Velcio does not provide /healthz. Implement GET /healthz in your app (HTTP 2xx) and redeploy. See Web delivery format. |
| Discord Worker offline / not in server | Buyer: check DISCORD_BOT_TOKEN, privileged intents, and bot invite. See Discord Worker apps in Buyer workflow. |
| Preview paused during review or verification | Use Restart preview (buyer in review; developer while verifying). Continuous free runtime is capped (default 120 minutes per run). |
| GitHub import unavailable or Connect missing | Developer: connect the Velcio GitHub App under Settings → Developer profile → Connected GitHub. If the UI says import is not configured, the environment has not enabled the App. See Developer workflow. |
| Hosting past due or app stopped after cancel | Buyer: update payment from the Apps list or project hosting panel; restart after the subscription allows runtime. See Hosting. |
| Cannot download source during review | Expected. Source ZIP download is available only after the project is completed (accept or auto-accept). |
| Cannot cancel during review | Expected. Use accept or dispute instead. See Cancelling a project in Buyer workflow. |