Troubleshooting cloud agent environments

Setup commands fail on a fresh container

Setup commands run in a new container on every cloud agent run. Commands that depend on existing directories, caches, or cloned repositories can fail with environment_setup_failed.

1. Update the setup commands so they work in a fresh container. For example, use mkdir -p .cache instead of mkdir .cache.
2. Use lockfile-based dependency commands such as npm ci when your project supports them.
3. Run the complete setup from a clean container before updating the environment.

”Setup command #N timed out”

A setup command that runs longer than 30 minutes fails environment setup. The error identifies the command number, command text, elapsed limit, and phase. If the phase is “resetting the working directory after the command”, the timeout is 30 seconds instead.

1. Inspect the named command and its output in the run’s transcript. Check for an interactive prompt, a long-running server, or a stalled download.
2. Make the command finish without user input. For example, use sudo apt-get install -y for package installation, and don’t start a foreground development server during setup.
3. Move lengthy dependency installation into your Docker image when possible, then test the revised setup from a fresh container and start a new run.

Permission denied or EACCES

Cloud agents run as a non-root user by default. A command fails when it needs root access or writes to a directory that the agent user cannot modify.

1. Prefix commands that require root access with sudo.
2. Make directories in the Docker image writable by UID and GID 1000.
3. Review configuring container users for the image and setup-command requirements.

external_authentication_required

Cloud agents need GitHub authorization to clone private repositories. This error can occur when GitHub lacks repository access or the user who started the run has not authorized GitHub.

1. Authorize GitHub for the user who starts the run.
2. For an automated workflow with an agent API key, configure team GitHub authorization.
3. Follow GitHub authorization setup for the full flow.

”VM failed before the agent could run”

This error often means the Docker image is incompatible with the agent runtime. Alpine Linux and other musl-based images are not supported because the runtime requires glibc.

1. Switch to a glibc-based image such as Debian, Ubuntu, or a default non-Alpine official image such as node, python, or rust.
2. Recreate or update the environment with the new image.
3. If the error continues, review the environment configuration in the Oz web app or use the Oz CLI to run oz environment get <ENV_ID>.

Related pages

• Cloud agent environments for the environment model and when to use one.
• Configuring cloud agent environments to create, update, and manage environments.
• environment_setup_failed for the API error reference.