ConvoyDocs

FAQ & Troubleshooting

Common questions and solutions to frequent issues.

Frequently asked questions

What languages and frameworks does Convoy Cloud support?

Convoy Cloud supports any application that can run in a container. With Dockerfile builds, you have full control — anything that runs in Docker runs on Convoy Cloud. With buildpack builds, languages are auto-detected including Node.js, Python, Go, Java, Ruby, PHP, .NET, and static sites. You can also deploy a pre-built container image directly with the Existing image option.

How long do builds take?

Typical builds take 1–3 minutes. Subsequent builds are faster due to caching. If the same commit and build method was already built, the cached image is reused with no build phase at all.

Can I deploy from a private repository?

Yes. When you install the Convoy Cloud GitHub App and grant repository access, Convoy Cloud can clone both public and private repositories.

Can I deploy monorepos?

Yes. Use the Build Context setting (Dockerfile mode) to specify the subdirectory containing your application.

What happens if my app crashes?

If health checks are enabled, Kubernetes automatically restarts your application. If the crash persists, check your logs to diagnose the issue. Convoy Cloud also automatically rolls back to the previous working version if a deployment fails.

My app is not accessible after deployment — what do I check?

  1. Ensure status is Deployed, not Deploying or Failed.
  2. Your app must listen on the configured port (default 8080) and bind to 0.0.0.0 — not 127.0.0.1. Binding to localhost only will make your app unreachable.
  3. If health checks are enabled, your app must respond to HTTP GET on the health check path with a 2xx or 3xx status.
  4. Check the Logs Explorer for startup errors.

Can I SSH into my container?

No. Use logs and metrics for debugging.

Is there a CLI?

Not yet. All operations are through the web dashboard. A CLI is planned.

What regions are available?

Convoy Cloud currently runs in Europe. Additional regions are planned.

Troubleshooting

Build failed

Check the build logs on the deployment detail page. Common causes:

  • Dockerfile syntax errors — validate locally with docker build .
  • Missing files — ensure all required files are in the build context
  • Dependency download errors — transient network failure. Try redeploying.

App deployed but not accessible

  1. Check status is Deployed.
  2. Ensure your app binds to 0.0.0.0 on the configured port, not 127.0.0.1.
  3. If health checks are enabled, verify your app returns 2xx/3xx on the health check path.
  4. Check logs for errors.

App keeps restarting

Usually means health check failures:

  1. Verify your app responds on the health check path.
  2. Ensure it starts within a reasonable time.
  3. Check logs for startup errors.
  4. Temporarily disable health checks to rule them out.

Custom domain not working

  1. Run dig app.example.com to confirm the DNS record resolves.
  2. Wait a few minutes for propagation.
  3. On the Domains page, the status should progress to Active. If stuck, try removing and re-adding the domain.

Build cache not working as expected

  • Dockerfile builds — put infrequently-changing steps first (COPY package.json before COPY .) so layers cache correctly.
  • Buildpack builds — cache is maintained automatically per repository.
  • Force rebuild — toggle off Reuse Existing Build in the deployment wizard to bypass the cache.

Workspace stuck on Provisioning

  1. Go to Workspace in the sidebar.
  2. Click Retry Provisioning.
  3. If it continues to fail, contact support.

Hitting the app count or per-app resource limit

App count limit — if you cannot create a new app and see a plan limit error:

  1. Delete an existing app to free the slot.
  2. Or upgrade to the Business plan for a higher app ceiling.

Per-app resource limit — if a resource preset is greyed out when configuring an app:

  1. The selected CPU or memory exceeds the per-app ceiling for your plan (0.5 vCPU / 1 GiB on Free; 4 vCPU / 8 GiB on Business).
  2. Reduce the resource configuration to fit within the ceiling, or upgrade to Business for higher per-app limits.

Grafana asked me to log in again

Click Open Grafana a second time. The handshake should complete silently because your Convoy Cloud session is still live. If it keeps prompting, sign in to Convoy Cloud from a normal (non-private) browser tab and retry. Private browsing can cause Grafana cookie issues.

I am looking at the wrong Grafana workspace

The Observability page always opens the Grafana organization that matches your active Convoy Cloud workspace. Switch workspaces from the Convoy Cloud sidebar, then click Open Grafana again. Do not switch organizations from inside Grafana.

Can someone in another workspace see my metrics or logs?

No. Each workspace has a dedicated Kubernetes namespace and a separate Grafana organization. Grafana datasources filter by namespace, and users from other workspaces have no membership in your organization.

Team Members

Invite and manage team members in your workspace.

On this page

Frequently asked questionsWhat languages and frameworks does Convoy Cloud support?How long do builds take?Can I deploy from a private repository?Can I deploy monorepos?What happens if my app crashes?My app is not accessible after deployment — what do I check?Can I SSH into my container?Is there a CLI?What regions are available?TroubleshootingBuild failedApp deployed but not accessibleApp keeps restartingCustom domain not workingBuild cache not working as expectedWorkspace stuck on ProvisioningHitting the app count or per-app resource limitGrafana asked me to log in againI am looking at the wrong Grafana workspaceCan someone in another workspace see my metrics or logs?