Deployment Failures

A launch can fail in two different ways, and the fix depends on which one happened. A bad request is rejected immediately, before anything is created or charged. A request that looked fine can still fail afterward, once a real provider tried and failed to build the machine, and that shows up as fields on the deployment itself rather than as an HTTP error. This page covers both, whether you launch from the dashboard or the API.

Errors returned immediately

These come back on the POST /api/v1/deployments call itself, in this shape:

{
  "error": {
    "code": "offer_unavailable",
    "message": "This offer is no longer available"
  }
}

Code	Status	Cause	What to do
`validation_error`	400	A required field is missing or malformed	Check the message and the `fields` map, then fix the request
`provider_not_supported`	400	The offer is a Vast.ai container offer. The API only launches virtual machines	Pick an offer with `deploymentType: virtual` from GET /api/v1/offers
`offer_provider_mismatch`	400	The `offer_id` belongs to a different provider than the `provider` field	Use the provider name from GET /api/v1/providers, not an offer’s `provider.slug`
`offer_unavailable`	400	The offer sold out or was withdrawn since you fetched it	Fetch offers again and pick another one
`image_incompatible`	400	The `os_image_id` cannot boot on this GPU (for example, an older driver image on a newer card)	Pick a different image from the provider’s image list
`image_not_offered`	400	The `os_image_id` is not in this provider’s catalog for this offer	Use one of the images the same endpoint lists for this offer
`invalid_ssh_key`	400	An SSH key ID is not one of yours, or the key material was rejected	Check the key still exists under SSH Keys, and try a different one
`invalid_volume`, `volume_unavailable`, `volume_provider_mismatch`, `volume_location_mismatch`	400	The volume you attached and the offer disagree about provider, location, or availability	Attach a volume in the same region and provider as the offer, or drop `volume_ids`
`insufficient_balance`	402	Your balance will not cover one hour at the offer’s rate	Add credit, then retry
`offer_cooling_down`	503	This offer, provider and location just failed on capacity and is suppressed for a short time	Wait for the time in the `Retry-After` header, or choose a different offer
`provider_maintenance`	503	The provider is in maintenance and new deployments on it are paused. Your running deployments keep running	Wait for the time in the `Retry-After` header, or choose an offer from another provider. See provider maintenance

On the dashboard, these show up as a message on the deploy page rather than as raw JSON, but the cause and the fix are the same.

The refund rule

Whatever the code, a launch that fails is refunded in full and automatically. The reserved first hour goes straight back to your credit balance, and nothing further is charged for that attempt. The same is true if you stop a deployment yourself before it reaches Running.

Offer cooling down, in more detail

offer_cooling_down is not personal to your account. The suppression is keyed to the exact offer, provider and location, so anyone requesting that same combination gets the same 503 until it clears, typically in about a minute. Read the Retry-After header (in seconds) rather than guessing, and either wait it out or move to a different offer with GET /api/v1/offers.

Every failure_code on a deployment

Once a request is accepted, a failure shows up on the deployment record instead of as an HTTP error: status becomes failed, and three fields explain it.

{
  "status": "failed",
  "failure_code": "SSH_KEY_MISSING",
  "retryable": false,
  "suggested_action": "Deploy with at least one RSA or Ed25519 SSH key from your account."
}

`failure_code`	Retryable	Meaning	What to do
`PROVIDER_CAPACITY`	Yes	The provider ran out of capacity for this offer and location between your request and the actual attempt	Retry in a few minutes, or choose another offer
`PROVIDER_MAINTENANCE`	Yes	The provider went into maintenance just after your request was accepted, so nothing was started there	Retry after the maintenance window, or choose another provider
`VOLUME_LOCATION_PINNED`	Yes	An attached volume pinned the deployment to one location, and that location had no capacity	Recreate the volume somewhere with capacity, or retry later
`VOLUME_LOCATION_MISMATCH`	No	The attached volume is in a different location than the instance	Attach a volume that lives in the same location as the instance
`IMAGE_INCOMPATIBLE`	No	The OS image cannot run on this GPU type, or is not offered for it	Choose a different OS image for this GPU
`OFFER_NOT_VM_CAPABLE`	No	A template was requested on a host without VM support	Choose an offer that supports VM templates
`SSH_KEY_REJECTED`	Yes	The provider rejected the SSH key material	Retry, and re-upload the key if it keeps happening
`SSH_KEY_MISSING`	No	No SSH key the provider accepts was sent, commonly an ECDSA-only key on QuantaCloud, which takes only RSA or Ed25519	Deploy with an RSA or Ed25519 key
`INVALID_DISK_SIZE`	No	The requested disk is below the provider minimum	Increase the disk size and try again
`INSUFFICIENT_BALANCE`	No	The first hour could not be reserved	Add credit and try again
`PROVIDER_INSTANCE_FAILED`	Yes	The instance was created, but the provider reported it failed	Retry. It usually lands on a different host
`INSTANCE_BOOT_TIMEOUT`	Yes	The instance never became ready within the wait window	Retry
`TUNNEL_NEVER_REGISTERED`	Yes	The instance booted, but its tunnel client never reached the tunnel server	Retry. If it keeps happening, the template’s startup script may be failing on this provider
`APP_HEALTH_TIMEOUT`	Yes	The tunnel connected, but the application never passed its health check, common with large images that take longer than the window to pull	Retry, or pick a smaller template
`USER_CANCELLED`	Yes	The deployment was stopped while it was still provisioning	No action needed
`WORKER_INTERRUPTED`	Yes	A platform worker restarted while this was provisioning, unrelated to you or the provider	Retry
`PLATFORM_PROVIDER_ISSUE`	Yes	A temporary platform-side problem with the provider connection	Retry shortly, or contact support if it persists
`DUPLICATE_REQUEST`	No	An internal request key collided on the provider’s side of a retry. This is not a client idempotency key: the API accepts none from you	Contact support if you see this repeatedly
`UNKNOWN`	Yes	The failure did not match any of the above	Contact support with the deployment ID

retryable describes whether trying again later, unchanged, could plausibly succeed. It is not a promise that DeployGPU retries anything automatically, and it is not a guarantee that a retry will work.

If you launch through the API, do not repeat a POST /api/v1/deployments call just because it timed out or your connection dropped. There is no idempotency key on that endpoint, so a repeated call after a network failure can create and bill a second GPU instead of finding the first one. List your deployments and look for a recent match before you send it again. See the deployments reference for the full request and response shapes.

My deployment disappeared from the list

This is expected, not a bug. The Deployments page only lists deployments in an active state (initializing, provisioning, connecting, running, stopping). Once a deployment reaches Failed or Interrupted, it drops out of that list. If you are looking at the page right when a launch fails, you will see the failure reason and suggested action once, in a banner. Navigate away, or reload later, and that deployment will not be listed again on the dashboard. An interruption, where a provider loses a machine that was already running, behaves the same way: a health check runs every 5 minutes, and if a provider confirms a machine is gone, the deployment is stopped and the unused time is refunded automatically, but no email is sent and the deployment disappears from the dashboard list the same way a failed one does. While a provider is in maintenance its answers are not trusted for this, so the health check does not stop deployments on that provider until the maintenance has ended. If you need to see a deployment after that point, the API returns every deployment regardless of status:

curl "https://api.deploygpu.ai/api/v1/deployments?size=100" \
  -H "X-API-Key: $DEPLOYGPU_API_KEY"

GET /api/v1/deployments and GET /api/v1/deployments/{id} never filter by status, so a failed or interrupted deployment is still there, with its failure_code or stop_reason intact.

When to contact support

Contact support with the deployment ID when failure_code is UNKNOWN or DUPLICATE_REQUEST, when a retryable failure keeps recurring on retry, or when PLATFORM_PROVIDER_ISSUE does not clear after a short wait. See Support for how to reach them.

Getting Started

Troubleshooting

Help

Deployment Failures

Errors returned immediately

The refund rule

Offer cooling down, in more detail

Every failure_code on a deployment

My deployment disappeared from the list

When to contact support

​Errors returned immediately

​The refund rule

​Offer cooling down, in more detail

​Every failure_code on a deployment

​My deployment disappeared from the list

​When to contact support

Errors returned immediately

The refund rule

Offer cooling down, in more detail

Every failure_code on a deployment

My deployment disappeared from the list

When to contact support