Copy page

Deploying & Source Control

Troubleshooting Stuck Deployments and Git Sync Errors

When a deploy seems to hang at Deploying api… or Building Developer Portal…, or your Git provider stops returning branches with a Bad Request or 410 Gone error, the cause is usually one of a few known issues. This guide helps you tell a genuinely stuck deploy from a slow-but-progressing one, fix Git source-control sync failures, and gather the right details before contacting support.

How a Zuplo deploy progresses

Every deploy, whether triggered by a Git push, the Zuplo CLI, or a save in the Portal, runs through two stages in order:

1. Deploying api…: Zuplo builds your gateway configuration (routes, policies, and modules) and rolls it out to the edge.
2. Building Developer Portal…: Zuplo builds the Developer Portal site from your OpenAPI document and portal configuration.

Each stage produces its own build logs. Zuplo separates logs by stage: api for the gateway build and dev-portal for the Developer Portal build. Knowing which stage a deploy stalled in tells you where to look.

Is the deploy stuck, or still working?

A deploy that looks frozen in the terminal is often still running on Zuplo's side. The Zuplo CLI doesn't run the build itself. It starts the deploy and then polls for the result. The build continues on the server even if the CLI stops waiting.

Confirm the server-side status first

Before assuming a deploy failed, check whether it actually completed:

1. Open your project in the Zuplo Portal.
2. Check the environment you deployed to. If the build finished, the environment shows the new deployment and its URL responds to requests.
3. Send a request to the environment URL (or its health check route, if you have one) to confirm the gateway is live.

If the environment is updated and serving traffic, the deploy succeeded. The CLI simply stopped waiting before the build reported back.

Extend the CLI polling timeout

By default the CLI polls every second for up to 250 attempts, a little over four minutes. Large projects can take longer to build, and when the CLI's poll budget runs out it stops waiting even though the deploy keeps running on the server.

Increase the timeout with the POLL_INTERVAL and MAX_POLL_RETRIES environment variables:

Code
# Poll every 5 seconds for up to 300 attempts (25 minutes)
POLL_INTERVAL=5000 MAX_POLL_RETRIES=300 zuplo deploy

• POLL_INTERVAL: Milliseconds between polls. Default 1000 (1 second).
• MAX_POLL_RETRIES: Maximum number of polls before the CLI times out. Default 250.

For the full command reference, see CLI: deploy.

The Developer Portal build never finishes

If the gateway (api stage) deploys but the overall deploy hangs at Building Developer Portal…, the problem is in the Developer Portal build, not your routes or policies.

Common causes:

• Invalid OpenAPI document: The portal is generated from your OpenAPI document. A malformed routes.oas.json, an unresolved $ref, or invalid schema can stall or fail the portal build. Validate your OpenAPI document and fix any errors.
• A legacy config/dev-portal.json file: Projects migrated from the old Developer Portal can carry a stale config/dev-portal.json that breaks the build. See the Dev Portal Migration Guide for the exact cleanup steps.
• Custom portal configuration errors: Errors in your zudoku.config.tsx (or other portal configuration) can prevent the site from building.

Read the dev-portal stage build logs to see the specific error, then redeploy after fixing it.

Git source-control sync errors

Zuplo connects to GitHub, GitLab, Bitbucket, and Azure DevOps for source control. The integration pushes and pulls code between the Portal and your repository, and it lists branches so you can map them to environments. When that authorization breaks, branch retrieval fails, often with a Bad Request or 410 Gone error.

Why branch retrieval returns Bad Request or 410 Gone

These errors come from the Git provider, not from Zuplo, and they almost always mean the connection is no longer authorized:

• The OAuth authorization Zuplo uses to reach the provider has expired or been revoked.
• The repository was renamed or moved, which breaks the existing connection.
• The Git app was uninstalled or lost access to the repository in the provider's settings.

410 Gone in particular signals that the resource Zuplo asked for (the branch list) is no longer available at that location, typically because the authorization or repository link behind it is stale.

Reconnect the integration

To restore branch sync, re-authorize the connection:

1. Open your project settings in the Zuplo Portal and select Source Control.
2. Disconnect the current repository connection.
3. Reconnect and complete the provider's authorization flow again, granting access to the repository that holds your Zuplo project.

After reconnecting, retrieving branches should succeed again.

Bitbucket-specific notes

Bitbucket integration is available on enterprise plans and provides push/pull source control without automatic deployments. You deploy with the Zuplo CLI through Bitbucket Pipelines.

If reconnecting from the Portal doesn't clear the sync error:

• Confirm Bitbucket is still enabled for your account. For bitbucket.org, Zuplo support enables the integration. Contact support@zuplo.com with your Bitbucket Workspace ID (found on your Workspace Settings page).
• For self-hosted Bitbucket, check the OAuth app. If the OAuth app's client secret was rotated or its callback URL or permissions changed, branch retrieval fails until the app is reconfigured. The callback URL must be https://portal.zuplo.com and the app must grant the repo, user, and read:org permissions. See Bitbucket Setup.

Decision tree

Use this to route yourself to the right fix:

Symptom	Most likely cause	First action
CLI hangs at Deploying api… then times out	Build took longer than the CLI's poll budget	Check the environment in the Portal; raise MAX_POLL_RETRIES
CLI reported timeout, but the environment is updated	Deploy completed after the CLI stopped waiting	None; capture the URL from the Portal
Deploy hangs at Building Developer Portal…	Developer Portal build error	Read the dev-portal build logs; validate OpenAPI; check for a stale config/dev-portal.json
Branch list fails with Bad Request or 410 Gone	Git authorization expired, revoked, or stale	Reconnect the integration in Source Control settings
Bitbucket still fails after reconnecting	Account not enabled, or OAuth app misconfigured	Contact support with your Workspace ID; check the self-hosted OAuth app

When to contact support

If you've worked through the relevant section above and the deploy or sync still fails, contact support@zuplo.com. Include these details so support can investigate without a round-trip:

• Your account and project names.
• The environment (branch) you're deploying to.
• The stage where it stalls (api or dev-portal) and the exact message you see.
• For sync errors: your Git provider, the repository, and the exact error text (for example, 410 Gone on branch retrieval).
• The approximate time of the failed deploy, in UTC.

Next steps

• Source Control & Deployments: how source control and deployments fit together across providers.
• Branch-Based Deployments: how branches map to environments and how environment URLs are named.
• Deploying Zuplo from a Monorepo: CI/CD configuration, schema validation, and health-check timeouts.
• Troubleshooting (local development): local dev server, ports, and certificate issues.