> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure Sandbox Troubleshooting

> What each Azure sandbox error means, what causes it, and how to fix it.

When an Azure sandbox cannot start or run a command, the agent reports Azure's or Genesis's own
message. The sections below are organized by where the problem shows up, and quote the messages
you will see. Values in angle brackets, such as `<rg>`, are filled in with your own names.

The fastest first step is always the agent check. Ask an agent:

```text theme={null}
Check whether the Azure sandbox backend is ready to use with my Azure connection.
```

It signs in as the service principal, reads the resource group, and checks the principal's
permissions there, then names the first thing that is wrong.

## The check or a start cannot find a connection

<AccordionGroup>
  <Accordion title="No accessible azure connection is configured">
    **Message:** `No accessible azure connection is configured. Configure a connection and retry.`

    **Cause:** You cannot use any Azure connection: none exists, or none is shared with you or
    your role.

    **Fix:** Create the connection, or ask an administrator to share it with you or your role; see
    [Create the Azure connection in Genesis](/docs/Setup/Azure-Sandboxes-Setup#create-the-azure-connection-in-genesis).
  </Accordion>

  <Accordion title="Choose an accessible azure connection and retry explicitly">
    **Message:** `Choose an accessible azure connection and retry explicitly, or ask the user which candidate to use.`

    **Cause:** You can use one or more Azure connections, but the request did not name one and
    neither you nor any of your roles has a default Azure connection. Genesis does not pick a
    connection on its own.

    **Fix:** Set the Azure connection as **My default**, or ask an administrator to set it as the
    **Role default** for your role. Or name the connection in your request ("use the
    `azure-sandboxes` connection").
  </Accordion>

  <Accordion title="Multiple azure role defaults conflict">
    **Message:** `Multiple azure role defaults conflict. Retry with an explicit connection or ask the user which candidate to use.`

    **Cause:** You have several roles whose default Azure connections differ.

    **Fix:** Set a **My default**, which takes precedence over role defaults, or name the
    connection in your request.
  </Accordion>

  <Accordion title="Region is not an Azure region name">
    **Message:** `'<value>' is not an Azure region name`

    **Cause:** The connection's **Region** is not formatted like an Azure region name. Genesis
    removes spaces and ignores case, so both forms Azure shows are accepted, for example
    `eastus2` or `East US 2`. This checks the name's format, not Azure's region list: a
    well-formed value that is not an actual region can pass connection validation and then be
    rejected by Azure when the sandbox starts.

    **Fix:** Edit the connection and set **Region** to an actual Azure region, such as `eastus2`.
  </Accordion>

  <Accordion title="Azure sandbox is missing a value">
    **Message:** `Azure sandbox is missing <fields> (looked in Azure connection '<name>').`

    **Cause:** The connection is missing a required field, such as the subscription ID or resource
    group.

    **Fix:** Edit the connection and fill in every required field; see
    [the field list](/docs/Setup/Azure-Sandboxes-Setup#create-the-azure-connection-in-genesis).
  </Accordion>

  <Accordion title="Azure sandboxes started here must use a Genesis Azure connection">
    **Message:**

    ```text theme={null}
    Azure sandboxes started here must use a Genesis Azure connection (credential_name or your default), not inline tenant_id, client_id or client_secret...
    ```

    **Cause:** The agent, or a skill or flow it followed, tried to pass Azure credentials directly
    instead of using a saved connection. Genesis refuses this so that every sandbox can be
    reattached and deleted later as the same identity.

    **Fix:** Save the credentials as an Azure connection and refer to it by name, or rely on your
    default. Remove the credentials from the skill, flow or instructions that supplied them.
  </Accordion>
</AccordionGroup>

## Signing in to Azure fails

<AccordionGroup>
  <Accordion title="Azure token request failed: 401 Unauthorized">
    **Message:**

    ```text theme={null}
    Azure token request failed: 401 Client Error: Unauthorized for url: https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
    ```

    **Cause:** Microsoft Entra ID refused the service principal's sign-in. Usually the client
    secret is wrong or has expired. A wrong client ID or tenant ID gives the same result.

    **Fix:** Check the tenant ID and client ID against the app registration's **Overview** page.
    If they match, create a new client secret (**Certificates & secrets** in the portal, or
    `az ad sp credential reset --id <appId> --append`), paste its **Value** into the Genesis
    connection, save, and run **Test Connection**.
  </Accordion>

  <Accordion title="Azure unreachable, or the token request times out">
    **Message:** `Azure unreachable: ...`, or a token request that fails with a connection error or
    timeout rather than an HTTP status.

    **Cause:** Genesis cannot reach `login.microsoftonline.com` or `management.azure.com` on port
    443\.

    **Fix:** Allow both destinations; see
    [Allow Genesis to reach Azure](/docs/Setup/Azure-Sandboxes-Setup#allow-genesis-to-reach-azure).
    In the Snowflake Native App, approve the connection's external access request.
  </Accordion>
</AccordionGroup>

## The check reports missing permissions

<AccordionGroup>
  <Accordion title="Cannot read resource group (HTTP 403)">
    **Message:**

    ```text theme={null}
    Cannot read resource group <rg> (HTTP 403); the service principal needs Contributor on it.
    ```

    **Cause:** Either the resource group name or subscription ID in the connection is wrong, or
    the service principal has no role on that resource group. Azure answers 403 in both cases, so
    the message cannot tell them apart.

    **Fix:** Check the subscription ID and resource group name in the connection, exactly as they
    appear in Azure. Then check the resource group's **Access control (IAM)** for a role
    assignment to the service principal. Assign **Contributor** or the
    [custom role](/docs/Setup/Azure-Sandboxes-Setup#least-privilege-alternative-custom-role) if
    there is none.
  </Accordion>

  <Accordion title="The service principal lacks containerGroups permissions">
    **Message:**

    ```text theme={null}
    The service principal lacks Microsoft.ContainerInstance/containerGroups/write, Microsoft.ContainerInstance/containerGroups/delete, Microsoft.ContainerInstance/containerGroups/containers/exec/action on resource group <rg>; grant Contributor (or those actions) there.
    ```

    **Cause:** The service principal can read the resource group but cannot manage container
    groups in it, typically because it has **Reader** there. **Test Connection** still succeeds in
    this case, because it only reads the resource group.

    **Fix:** Assign **Contributor** or the
    [custom role](/docs/Setup/Azure-Sandboxes-Setup#least-privilege-alternative-custom-role) on
    the resource group. Role assignments can take a minute or two to apply; wait, then run the
    check again.
  </Accordion>
</AccordionGroup>

## A sandbox does not start

<AccordionGroup>
  <Accordion title="403 AuthorizationFailed">
    **Message:**

    ```text theme={null}
    Azure rejected container group genesis-sbx-<id>: 403 AuthorizationFailed: The client '<appId>' ... does not have authorization to perform action 'Microsoft.ContainerInstance/containerGroups/write' over scope ...
    ```

    **Cause:** The same as the missing-permissions message above: the service principal cannot
    create container groups in this resource group.

    **Fix:** Assign **Contributor** or the custom role on the resource group, wait a minute or two,
    and try again.
  </Accordion>

  <Accordion title="MissingSubscriptionRegistration">
    **Message:** Azure's error code `MissingSubscriptionRegistration`, saying the subscription is
    not registered to use namespace `Microsoft.ContainerInstance`. The exact wording comes from
    Azure.

    **Cause:** The Container Instances resource provider is not registered on the subscription.
    This is common on new subscriptions.

    **Fix:** Have an Azure administrator register it, then try again:

    ```bash theme={null}
    az provider register --namespace Microsoft.ContainerInstance
    az provider show -n Microsoft.ContainerInstance --query registrationState -o tsv
    ```

    See [Register Azure Container Instances](/docs/Setup/Azure-Sandboxes-Setup#prepare-azure).
  </Accordion>

  <Accordion title="400 InaccessibleImage">
    **Message:**

    ```text theme={null}
    Azure rejected container group genesis-sbx-<id>: 400 InaccessibleImage: The image '<image>' in container group '<group>' is not accessible. Please check the image and registry credential.
    ```

    **Cause:** Azure could not pull the image. The image name or tag is wrong, or the image is in a
    private registry and no registry credentials, or the wrong ones, were given.

    **Fix:** Check the image name and tag. For a private registry, have the agent pass
    `registry_server`, `registry_username` and `registry_password`; see
    [Private registries](/docs/Setup/Azure-Sandboxes-Using#private-registries).
  </Accordion>

  <Accordion title="An error response is received from the docker registry 'index.docker.io'">
    **Message:**

    ```text theme={null}
    An error response is received from the docker registry 'index.docker.io'. Please retry later.
    ```

    **Cause:** Docker Hub limits anonymous image downloads from the shared addresses Azure
    Container Instances uses.

    **Fix:** Use an image from Microsoft Container Registry (`mcr.microsoft.com`) or your own Azure
    Container Registry. The default image already comes from Microsoft's mirror, so leaving the
    image unset avoids this.
  </Accordion>

  <Accordion title="Container group did not start, or was not running after 600s">
    **Message:** `Container group genesis-sbx-<id> did not start: <Azure's events>`, or
    `Container group genesis-sbx-<id> was not running after 600s`

    **Cause:** Azure created the container group but the container failed or never reached the
    running state. The events Azure reported are included in the first message. Common causes are
    an image that is not a Linux image, an image that cannot start a shell, a size larger than the
    region allows, or a regional capacity or quota limit.

    **Fix:** Read the events in the message. Try the default image to rule out the image, a smaller
    size to rule out limits, or an Azure connection set to another region. Genesis deletes a container group that fails to
    start, so nothing is left behind.
  </Accordion>
</AccordionGroup>

## A sandbox starts, but commands fail

<AccordionGroup>
  <Accordion title="Failed to open ACI exec session: cannot connect to exec host">
    **Message:**

    ```text theme={null}
    Failed to open ACI exec session: cannot connect to exec host <id>.<region>.atlas.cloudapp.azure.com:19390: ...
    ```

    or
    `Failed to open ACI exec session: cannot resolve exec host <id>.<region>.atlas.cloudapp.azure.com:19390: ...`

    **Cause:** Genesis cannot reach Azure's command endpoint for the region. The sandbox started,
    because that uses port 443, but commands use port **19390**. Usually:

    * An outbound firewall allows only port 443.
    * In the Snowflake Native App, the connection's external access has not been approved, was
      approved for a different region than the sandbox runs in, or the network rule lacks the
      `:19390` port. Snowflake reports a blocked destination as
      `[Errno -2] Name or service not known`. Genesis can still show the connection as ready,
      because it cannot read the network rule's contents.
    * Genesis's DNS cannot resolve the endpoint's host name. Genesis retries briefly, because a
      new container's host name can take a few seconds to appear.

    **Fix:** Allow `*.<region>.atlas.cloudapp.azure.com` on port 19390; see
    [Allow Genesis to reach Azure](/docs/Setup/Azure-Sandboxes-Setup#allow-genesis-to-reach-azure).
    In the Snowflake Native App, approve the connection's external access again and make sure the
    connection's **Region** matches the region the sandbox runs in. If your administrator manages
    the network rule by hand, it must contain `*.<region>.atlas.cloudapp.azure.com:19390` exactly:
    `*.cloudapp.azure.com` does not match, because a Snowflake wildcard covers one subdomain level.
    Rule changes take effect within about 20 seconds; ask the agent to run the command again.
  </Accordion>

  <Accordion title="Command timed out">
    **Message:** `Command timed out after <N>s`, with exit code 124.

    **Cause:** The command ran longer than its time limit, five minutes unless the agent set
    another.

    **Fix:** Ask the agent to run it with a longer timeout, to run it in the background and check
    on it, or to split the work into smaller steps.
  </Accordion>

  <Accordion title="ACI exec transport failed">
    **Message:** `ACI exec transport failed: ...`, for example `exec session closed by Azure`.

    **Cause:** The command session with Azure dropped, or a transfer kept failing its integrity
    check. Genesis never returns damaged output: it retries and then reports this error instead.

    **Fix:** Ask the agent to run the command again. If it keeps happening, check whether the
    sandbox is still running (it may have reached its maximum lifetime) and whether the network
    path to port 19390 is stable.
  </Accordion>

  <Accordion title="A package install fails">
    **Message:** Errors from `pip` such as connection timeouts or `Could not find a version that
            satisfies the requirement`.

    **Cause:** If the sandbox is attached to your virtual network, its outbound traffic is
    following your network's rules, which may block `pypi.org`. Otherwise, the package name or
    version may be wrong.

    **Fix:** Check that the subnet has an outbound path to the internet, such as a NAT gateway or a
    route through your firewall, and allow `pypi.org` and `files.pythonhosted.org` on port 443 from
    it, or use your own package mirror; see
    [Run inside your virtual network](/docs/Setup/Azure-Sandboxes-Using#run-inside-your-virtual-network).
  </Accordion>
</AccordionGroup>

## Container groups are left in the resource group

Genesis deletes a sandbox's container group when it stops, times out, or is found ended after a
restart. A container whose maximum lifetime has passed has already exited and no longer bills for
compute; Genesis deletes its group the next time its sandbox monitor runs. If groups remain, for
example after Genesis was removed or the service principal lost access, list and delete them:

```bash theme={null}
az container list --resource-group genesis-sandboxes -o table
az container delete --resource-group genesis-sandboxes --name genesis-sbx-<id> --yes
```

Every container group Genesis creates is named `genesis-sbx-<id>` and tagged
`genesis-sandbox: true`. Groups started by an agent also carry `genesis-session` and `genesis-bot`
tags naming the Genesis session and agent.

## Collecting details for support

If you need help from Genesis support, send:

1. **The exact message**, copied from the chat or the Sandbox Sessions page, and the time it
   happened, with time zone.
2. **The result of the agent check** ("Check whether the Azure sandbox backend is ready to use
   with my Azure connection").
3. **Where Genesis runs**: Snowflake Native App, Docker, Kubernetes or a virtual machine.
4. **The connection's region and resource group**, and the role assigned to the service
   principal (Contributor or the custom role).
5. **The container group name** (`genesis-sbx-<id>`), if a sandbox started.
6. **For start failures**, the container group's events, if it still exists:

   ```bash theme={null}
   az container show --resource-group genesis-sandboxes --name genesis-sbx-<id> \
     --query "containers[0].instanceView.events" -o table
   ```

<Warning>
  Never send the client secret. Support never needs it. If it was pasted anywhere by mistake,
  create a new secret and delete the old one.
</Warning>