Troubleshooting MicroVMs

Last verified 19 Nov 2026

DigitalOcean MicroVMs are lightweight virtual machines that run a container image in an isolated kernel, pause automatically when idle, and resume on the next request with memory, files, and processes intact.

The following sections describe common problems with DigitalOcean MicroVMs and how to resolve them.

A MicroVM Is in the Failed State

If a MicroVM is in the failed state, the failure_reason field in the API response explains why. doctl compute microvm get shows the same text under Failure Reason, and the Control Panel shows it on the Lifecycle card. Common causes are an image that cannot be pulled, a container that exits, and a VPC network that is in another region or belongs to another team.

You cannot recover a failed MicroVM. Destroy it and create a new one.

Docker Fails to Start Inside a MicroVM

If dockerd fails to start inside a MicroVM, for example with errors about a missing cgroup mount or a missing CAP_SYS_ADMIN capability, the image is a Docker-in-Docker image. MicroVMs do not support Docker-in-Docker images. Use an image that runs your workload directly instead.

Requests Fail While the MicroVM Is Paused

If a request to a URL, a command, a console, or a file transfer fails while the MicroVM is paused, check whether auto-resume is off. If it is, resume the MicroVM manually. You cannot change auto-resume after creation.

Outbound Connections Fail

If the MicroVM has an outbound policy, check the following:

  • HTTP requests return 403, or HTTPS connections close during the handshake: The destination is not allowed. Check the MicroVM’s rules on its Overview tab under Outbound network, or in the egress_policy field of the API response. A wildcard such as *.example.com does not match example.com itself, and an IP rule does not match a hostname that resolves to that IP address. You cannot change the rules, so create a new MicroVM with the rules you need.
  • Connections time out or are refused, even to allowed hosts: The client is not using the proxy, or the connection is not HTTP or HTTPS. Make sure your client honors the HTTP_PROXY and HTTPS_PROXY environment variables, and that your application did not overwrite them. SSH, database connections, and other non-HTTP protocols are always blocked.

HTTPS Requests Fail with a Certificate Error

If HTTPS requests to a host with an outbound credential fail with a certificate verification error, your client does not trust the platform’s certificate authority. Point your client to /etc/ssl/certs/microvm-ca-bundle.crt, or import /etc/ssl/certs/microvm-interception-ca.pem into your runtime’s trust store, such as the Java trust store. Clients that pin certificates cannot use credentials. For details, see Use Credentials with HTTPS.

A Checkpoint Cannot Be Restored

If creating a MicroVM from a checkpoint fails with a message that the origin MicroVM’s environment or egress credentials are no longer available, the MicroVM the checkpoint was taken from has been destroyed, and its stored environment variables or credentials were deleted with it. You cannot create MicroVMs from that checkpoint. Create a new MicroVM from a container image instead.

The Console Fails with a Raw Mode Error

If doctl compute microvm console fails with raw mode: operation not supported by device, doctl is not running in an interactive terminal. Run the command from a terminal, not from a script or a pipe.

Opening a Console Returns HTTP 429

HTTP 429 when opening a console usually means the MicroVM already has four consoles open. A console whose client disconnected without closing it, for example because a laptop went to sleep, can hold its slot for a while before it closes. Close other consoles, or wait and try again.

A Console Closes After 30 Minutes

A console closes when it receives no input for 30 minutes, even if the shell is still printing output. Two minutes before it closes, the console sends an idle_warning message. To keep a long task running after the console closes, start it with nohup or with its output redirected. For details, see Run Longer Tasks.

A Command Times Out

If a command fails after 40 seconds, it either took too long or started a background process that still holds its output open. Run long tasks in the background with their output redirected, as shown in Run Longer Tasks.

A File Transfer Returns HTTP 409

HTTP 409 on a file upload or download means one of the following:

  • The workload container is not running. Check the MicroVM’s state.
  • The path is a directory, device, or symbolic link rather than a regular file.
  • The MicroVM was created before file transfer was available. Create a new MicroVM to use file transfer.

Creating a MicroVM Returns HTTP 403

HTTP 403 on create means the token is missing a scope, or your team has reached its MicroVM limit. The limit counts both running and paused MicroVMs. To see your team’s limits, run doctl compute microvm options or send a GET request to /v2/microvms/options. To free up capacity, destroy MicroVMs you no longer need.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.