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. |
| Custom Dockerfile base cannot be pulled | Confirm the image is public, is a Linux image for the build-host architecture, and the registry is reachable. Private-registry credentials are not supported yet. |
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 | Velcio supplies the default route. Check the app’s port, deployment readiness and health configuration. A custom health path must be implemented by the app. Web delivery format. |
| Cannot send Web delivery to review | Public GET /healthz must return HTTP 2xx on the preview URL. Check startup, port binding and health configuration, 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. |
Database and storage
Managed connections are injected at runtime once provisioning is ready. If DATABASE_URL is still missing, check the resource status before entering another connection string. Free limits are shared with the buyer’s other apps. Paid data-service usage is separate from the hosting allowance.
The hosting offer starts at first hosting activation after acceptance. Cancelling or restarting does not reset its end date. See the exact dates and rate in Cloud billing.