[Bug]: `e2b template migrate` writes `template_id` into the `name` slot of `build_prod.py`, causing 409 alias collision on rebuild

[carrotRakko]

Sandbox ID or Build ID

(n/a — this is a CLI bug, not a sandbox runtime issue)

Environment

• E2B CLI: 2.12.2 (current npm latest)
• Python: 3.12.13
• e2b (Python SDK): 2.26.0
• OS: Debian-based Linux container

Timestamp of the issue

2026-06-24 04:16 UTC

Frequency

Happens every time (when migrating an existing template)

Expected behavior

After e2b template migrate -l python-async is applied to an existing template's e2b.toml, the generated build_prod.py should be runnable and rebuild the existing template in place (cache-hit when the Dockerfile content is unchanged).

Actual behavior

python build_prod.py fails with:

e2b.exceptions.BuildException: 409: Alias 'abc1234567890xyz' is already used

(abc1234567890xyz above is a placeholder; the actual template_id from our environment has been redacted.)

The generated script writes the source template's template_id (internal opaque ID, e.g. abc1234567890xyz) into the second positional argument of AsyncTemplate.build. Per the SDK, that argument is the template name (human-readable alias), not the template_id. Passing the existing ID as a new alias collides with itself.

The dev variant happens to succeed because the generated name is <template_id>-dev, which is a fresh unused alias — so the bug only surfaces when the user actually tries to push to prod.

Issue reproduction

1. Have an existing E2B template — for example, alias my-template, template_id abc1234567890xyz.
2. In a directory with a complete v1 e2b.toml:

   team_id = "..."
   template_id = "abc1234567890xyz"
   dockerfile = "e2b.Dockerfile"

   and the corresponding e2b.Dockerfile, run:

   e2b template migrate -l python-async
   

3. Migration succeeds; the generated build_prod.py reads:

   await AsyncTemplate.build(
       template,
       "abc1234567890xyz",   # the template_id
       on_build_logs=default_build_logger(),
   )

4. Run python build_prod.py (after working around the relative-import issue from [Bug]: e2b template migrate Python output is not runnable as instructed (relative import vs python build_dev.py) #1477).
5. Observe: e2b.exceptions.BuildException: 409: Alias 'abc1234567890xyz' is already used.

Additional context

Why template_id is the wrong value here

AsyncTemplate.build docstring:

:param name: Template name in 'name' or 'name:tag' format
:param alias: (Deprecated) Alias name for the template. Use name instead.

name is the human-readable alias (e.g. my-template), not the internal template_id. Passing the existing template_id as name makes the API try to create a new template with that string as a new alias, which already exists → 409.

The fix that actually rebuilds the existing template

Replacing the argument with the existing alias works as expected:

await AsyncTemplate.build(
    template,
    "my-template",   # the existing alias
    cpu_count=2,
    memory_mb=1024,
    on_build_logs=default_build_logger(),
)

Verified locally end-to-end:

• python build_prod.py succeeded; the build log shows Template created with ID: <existing-template_id> (i.e. it routed to the existing template, not a new one), and every layer hit cache (CACHED [base] FROM e2bdev/base, etc.) because the Dockerfile content is unchanged.
• After the rebuild, Sandbox.create("my-template", ...) spawns successfully and executes commands — confirming the rebuilt template is intact.

Where in the codebase

Likely the migration code substitutes template_id from the parsed e2b.toml into the name slot of the generated build script (e.g. packages/cli/src/templates/python-build-async.hbs consuming a template_id field from the migration context built in packages/cli/src/commands/template/migrate.ts). The same pattern would affect python-build-sync.hbs and typescript-build.hbs.

Possible fix (deferring to maintainers for direction)

The migration should write the human-readable alias into the generated name, not the opaque template_id. Sources for the alias could be:

• Resolve via the templates API using the template_id (since e2b template list shows the alias is stored server-side).
• Accept an --alias flag on e2b template migrate for users whose e2b.toml doesn't carry the alias inline.
• Prompt interactively when ambiguous.

Happy to send a PR once you confirm the direction.

Related

• [Bug]: e2b template migrate Python output is not runnable as instructed (relative import vs python build_dev.py) #1477 — a separate template migrate bug where generated Python scripts use a relative import (from .template import template) but the printed instructions tell users to run them as single files (python build_dev.py), producing ImportError: attempted relative import with no known parent package.

✍️ Author: Claude Code with @carrotRakko (AI-written, human-approved)

[linear-code]

ENG-4347

[Solaris-star]

Opened a fix in #1563 — prefer template_name / resolved alias over opaque template_id as the migrate build name so prod rebuilds don't 409.