Troubleshooting
Fix common Velcio issues: secrets, builds, 502s, live preview, GitHub import and hosting renewals when something fails.
Published · Updated
Common blockers for buyers and developers. Full paths: Buyer workflow, Developer workflow.
Deploy and secrets
| 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. |
| Worker offline / not doing expected work | Buyer: check production secrets and logs. Worker secrets in Buyer workflow. |
Build and packaging
| Symptom | What to try |
|---|---|
| Build or validation failed | Developer: fix layout (Delivery format), resubmit ZIP/GitHub or Retry deploy / Rebuild. |
| WordPress / PHP CMS rejected | Expected. Not supported. Ship a Worker/Web app. Not supported. |
Choose Worker or Web before submit: Choosing Worker or Web.
Web preview and health
| Symptom | What to try |
|---|---|
| Web public URL returns 502 | Listen on 0.0.0.0 with env PORT (Velcio sets 8080). Wrong bind/port is the usual cause. Web delivery format. |
Web /healthz returns 404 | Implement GET /healthz in your app (HTTP 2xx) and redeploy. Velcio does not add the route. Web delivery format. |
| Cannot send Web delivery to review | Public GET /healthz must return HTTP 2xx on the preview URL. Fix the route or startup, redeploy if needed, then confirm again. Web delivery format. |
Review and preview time
| Symptom | What to try |
|---|---|
| Preview paused during review or verification | Restart preview (buyer in review, developer while verifying). Cap is default 120 minutes per continuous run. |
| Cannot download source during review | Expected. ZIP download only after completed (accept or auto-accept). |
| Cannot cancel during review | Expected. Accept or dispute instead. Cancelling in Buyer workflow. |
GitHub import
| Symptom | What to try |
|---|---|
| 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. Developer workflow. |
Hosting and billing
| Symptom | What to try |
|---|---|
| Hosting past due or app stopped after cancel | Buyer: update payment from Apps or project hosting. Restart when the subscription allows. Hosting. |