Translate AMI/region mismatch into a clear error

Now that region is resolved from the boto3 chain rather than a required
config field, an eval that hardcodes ami_id (the README's recommended
"portable eval" shape) but is silent on region will pick up the runner's
AWS_DEFAULT_REGION. If that differs from the AMI's region, run_instances
fails with a raw InvalidAMIID.NotFound — opaque to someone running an eval
they didn't write.

Translate the AMI-not-found ClientError (and the empty describe_images
result on the volume_size path) into a ValueError naming the AMI, the
resolved region, and the fix (set INSPECT_EC2_SANDBOX_REGION, or omit
ami_id to auto-resolve for the region).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: art-dsit

src/ec2sandbox/_instance_provider.py

@@ -34,6 +34,23 @@
 # default provider's ``find_sandbox_instances`` can discover them.
 MARKER_TAG_KEY = "inspect_sandbox"
 
+# EC2 error codes meaning "this AMI ID isn't in this region". Turned into a
+# clear ValueError so the common footgun — running an eval that hardcodes an
+# AMI in a different region from the one the session resolved — is legible.
+_AMI_NOT_FOUND_CODES = frozenset(
+    {"InvalidAMIID.NotFound", "InvalidAMIID.Malformed", "InvalidAMIID.Unavailable"}
+)
+
+
+def _ami_region_mismatch_error(ami_id: str, region: str) -> ValueError:
+    return ValueError(
+        f"AMI '{ami_id}' was not found in region '{region}'. AMI IDs are "
+        "region-scoped, so an eval that hardcodes ami_id only runs in that "
+        "AMI's region. Set INSPECT_EC2_SANDBOX_REGION (or the config's region) "
+        "to the AMI's region, or omit ami_id to auto-resolve the Ubuntu 24.04 "
+        "image for the resolved region."
+    )
+
 
 @dataclass(frozen=True)
 class ProvisionedInstance:
@@ -166,7 +183,9 @@ def _root_device_name(ec2_client: Any, ami_id: str) -> str:
     resp = ec2_client.describe_images(ImageIds=[ami_id])
     images = resp.get("Images", [])
     if not images:
-        raise ValueError(f"AMI {ami_id} not found when resolving root device name")
+        # Almost always an AMI/region mismatch (describe_images returns an
+        # empty list rather than erroring for a foreign-region AMI).
+        raise _ami_region_mismatch_error(ami_id, ec2_client.meta.region_name)
     return images[0]["RootDeviceName"]
 
 
@@ -290,7 +309,15 @@ async def create_instance(
                     "Ebs": {"VolumeSize": volume_size},
                 }
             ]
-        response = ec2_client.run_instances(**instance_params, MinCount=1, MaxCount=1)
+        try:
+            response = ec2_client.run_instances(
+                **instance_params, MinCount=1, MaxCount=1
+            )
+        except ClientError as e:
+            code = e.response.get("Error", {}).get("Code")
+            if code in _AMI_NOT_FOUND_CODES:
+                raise _ami_region_mismatch_error(ami_id, region) from e
+            raise
         instance = response["Instances"][0]
         instance_id = instance["InstanceId"]
 

tests/ec2sandboxtest/test_instance_provider.py

@@ -1,6 +1,7 @@
 from unittest import mock
 
 import pytest
+from botocore.exceptions import ClientError
 
 from ec2sandbox._instance_provider import DefaultEc2InstanceProvider
 from ec2sandbox.schema import Ec2SandboxEnvironmentConfig
@@ -128,6 +129,40 @@ async def test_create_instance_stamps_session_resolved_region():
     assert ec2_call.kwargs["region_name"] is None
 
 
+@pytest.mark.asyncio
+async def test_run_instances_ami_not_found_raises_region_hint():
+    """A region-scoped AMI missing in the resolved region gets a clear error."""
+    provider, ec2_client, _ = _make_provider_with_mocks(_make_config())
+    ec2_client.meta.region_name = "us-east-1"
+    ec2_client.run_instances.side_effect = ClientError(
+        {"Error": {"Code": "InvalidAMIID.NotFound", "Message": "nope"}},
+        "RunInstances",
+    )
+
+    with pytest.raises(ValueError, match="region-scoped"):
+        await provider.create_instance(
+            instance_type="t3a.micro",
+            ami_id="ami-123",
+            tags=[("Name", "x")],
+        )
+
+
+@pytest.mark.asyncio
+async def test_volume_size_ami_not_found_raises_region_hint():
+    """describe_images returning no images (foreign-region AMI) is translated too."""
+    provider, ec2_client, _ = _make_provider_with_mocks(_make_config(volume_size=100))
+    ec2_client.meta.region_name = "us-east-1"
+    ec2_client.describe_images.return_value = {"Images": []}
+
+    with pytest.raises(ValueError, match="region-scoped"):
+        await provider.create_instance(
+            instance_type="t3a.micro",
+            ami_id="ami-123",
+            tags=[("Name", "x")],
+            volume_size=100,
+        )
+
+
 @pytest.mark.asyncio
 async def test_create_instance_with_volume_size_sets_block_device_mappings():
     provider, ec2_client, _ = _make_provider_with_mocks(_make_config(volume_size=100))