langchain-ai/deepagents · error · RuntimeError

Failed while waiting for Vercel sandbox startup.

Error message

Failed while waiting for Vercel sandbox startup.

What it means

`_wait_until_running` polls a Vercel sandbox until it reaches the running state; when waiting fails for any reason other than the handled timeout, it raises RuntimeError with this generic message. The wording is deliberately vague to avoid leaking credentials embedded in Vercel SDK exceptions, while `raise ... from exc` preserves the underlying cause for debugging.

Source

Thrown at libs/code/deepagents_code/integrations/sandbox_factory.py:1054

        if status == "running":
            return
        if status in _VERCEL_TERMINAL_STATUSES:
            msg = f"Vercel sandbox {sandbox.sandbox_id} is in terminal state {status!r}"
            raise RuntimeError(msg)

        try:
            sandbox.wait_for_status("running", timeout=timeout)
        except TimeoutError as exc:
            status = str(sandbox.status)
            msg = (
                f"Vercel sandbox {sandbox.sandbox_id} failed to start within "
                f"{timeout} seconds; current status is {status!r}"
            )
            raise RuntimeError(msg) from exc
        except Exception as exc:  # Vercel SDK exception types vary by version
            # Generic message avoids leaking credentials; chain preserves cause.
            msg = "Failed while waiting for Vercel sandbox startup."
            raise RuntimeError(msg) from exc


def _get_provider(
    provider_name: str,
    registry: SandboxRegistry | None = None,
) -> SandboxProvider:
    """Get a `SandboxProvider` instance for the specified provider (internal).

    Args:
        provider_name: Name of the provider. Resolved through the registry so
            built-in, entry-point, and config providers are all supported.
        registry: An already-built registry to reuse. A fresh one is loaded
            when omitted.

    Returns:
        `SandboxProvider` instance. Propagates `ValueError` from the registry
            if `provider_name` is unknown.
    """

View on GitHub (pinned to a1af029e6e)

Solutions

1. Inspect the chained cause: catch the RuntimeError and print/log `__cause__` for the real Vercel error.
2. Verify the Vercel API token and team/project configuration are valid and unexpired.
3. Retry `get_or_create` — transient Vercel/network failures during sandbox boot are common.
4. Pin/check the Vercel SDK version; exception behavior varies between versions.

Example fix

// before
sandbox = get_or_create('vercel')
// after
try:
    sandbox = get_or_create('vercel')
except RuntimeError as exc:
    logger.error('Vercel sandbox startup failed: %s', exc.__cause__)
    raise

# preflight: confirm token/creds configured before creating sandbox
import os
assert os.environ.get('VERCEL_TOKEN') or vercel_config_token, 'Vercel token missing'

for attempt in range(3):
    try:
        sandbox = get_or_create('vercel')
        break
    except RuntimeError as exc:
        cause = exc.__cause__
        logger.warning('vercel startup attempt %d failed: %s', attempt, cause)
        if attempt == 2:
            raise

When it happens

Trigger: Calling `get_or_create` for a Vercel sandbox where the underlying Vercel SDK call inside the wait loop throws — e.g. authentication failure, sandbox id not found, API 5xx, or SDK version-specific exception types.

Common situations: Expired or invalid Vercel API token, Vercel service outage or rate limiting, deleted team/project referenced by config, or upgrading the Vercel SDK so exception classes changed shape.

Related errors

• enable_interpreter=True is not supported with a remote sandb
• Server graph '{graph_name}' did not initialize within {timeo
• Missing dependencies for '{provider}' sandbox. {install_hint
• Sandbox provider '{name}' config is missing 'class_path'
• Unknown sandbox provider: {name}. Available providers: {', '

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/ae7b1c427783c34d. Report an issue: GitHub.