Troubleshooting
Sign-in expired
When an AWS sign-in has expired, the main window says Sign in to AWS. For an IAM Identity Center profile, choose Sign In… and finish in your browser, or run aws sso login --profile <name> in Terminal. For a profile with a credential helper, check the helper; for access keys, check ~/.aws.
A region isn't listed
Settings → General → Regions to list holds the regions the main window and menu bar list for the profile Settings shows. Only its default region is listed until you add more, and the default region is always listed. If your organization blocks a region, the main window offers Stop Listing it.
A region won't add
Pressing Add on a region MicroVMs aren't known to run in checks it first. It says:
- Lambda MicroVMs aren't available in the region: nothing was added. Choose another region.
- Permission needed: your AWS identity isn't allowed to call
lambda:ListManagedMicrovmImages, so the region couldn't be checked. Add that permission, or choose Add Anyway. - Sign in to AWS, or another message about the sign-in or the network: the region couldn't be checked. Sign in again and try once more, or choose Add Anyway.
A launch or connect takes a long time
A MicroVM that takes longer than 90 seconds to start isn't treated as failed. The sidebar says taking longer than usual, and the terminal's progress does too, and MicroVM Studio keeps checking every 5 seconds until the MicroVM runs or stops. Mounting storage and a large image are the usual reasons. Nothing needs doing; if it ends up stopped, the message says why.
Memory quota reached
Your AWS account can't run more MicroVM memory at once: each MicroVM counts its image's size against a quota for its architecture. Terminate a MicroVM, use an image with a smaller size (see Images), or ask AWS for a higher quota. When a launch or a resume hits it, the main window's message has Open Service Quotas, which opens the page where you can ask for more. In a terminal pane, the message gives that page's address instead.
"This MicroVM is suspended"
A pane says this when it reconnected by itself, such as after your Mac woke, and found the MicroVM suspended while its workspace's Resume on connect is off. Choose Resume and Reconnect to resume it, or turn Resume on connect back on in the workspace's Time limits section.
A setup step failed
The terminal shows which step failed and its output, with secrets hidden. Try Again runs setup again. Open Shell Anyway connects once without any setup: no credentials, repos or start command, just the MicroVM's own shell, to look around. It never mounts /workspace, but with persistent storage it opens there when /workspace is mounted already, as an image with lifecycle hooks does at launch; otherwise it opens in your home folder. A missing secret goes in Settings → Secrets. Setup gives up after 15 minutes.
"This MicroVM can't reach github.com"
Setup stops at Cloning repos when the MicroVM has no internet. That happens on a VPC network connector whose subnets don't route out through a NAT gateway, as with a persistent /workspace: add the route in your VPC (see Network Connectors), then launch a new MicroVM. A workspace that doesn't need your VPC can use Internet (default) as its network connector. Before it clones, setup gives github.com 10 seconds to answer, and a clone that stalls for 30 seconds fails instead of hanging.
The start command exits
If the shell closes within 10 seconds of connecting, the pane says The shell closed right after it started and doesn't retry. Edit the workspace's start command, or clear it and run the command by hand to see what it prints.
"Mounting /workspace" failed
- This image can't mount EFS: update the starter image in Settings → Images, or choose an image built with All OS capabilities.
- It took over a minute: check that the file system's subnets and security groups still exist, and look at its health and mount targets: View… in Settings → Storage.
- The file system isn't on this Mac any more: edit the workspace and choose another, or None.
With lifecycle hooks, a mount that failed at launch is tried again when the terminal connects; if that fails too, the output says why the first one failed.
Permissions
The permission check is in Settings → General → Permissions: choose Check Permissions. It checks the profile Settings shows, in its default region, and shows what your AWS identity can do, in six groups: Run MicroVMs, Open shells, Build images, Use and create IAM roles (optional), Use VPC network connectors (optional) and Keep /workspace on EFS (optional). Copy Policy copies a minimal IAM policy to add to your user or role. It includes the roles your saved workspaces and connectors use.
No warnings appear
Time-left and idle warnings are notifications: allow them for MicroVM Studio in System Settings → Notifications.