dagger/dagger · error · ClientConnectionError

No active engine session to connect to

Error message

No active engine session to connect to

What it means

Raised by ClientConnection.session() when no ConnectParams could be resolved — neither explicit params nor DAGGER_SESSION_HOST from the environment — so there is no active engine session to connect to. The SDK defers environment checks until a session is actually needed.

Source

Thrown at sdk/python/src/dagger/client/_session.py:248

            logger.warning(
                "Cannot set connection config after connection already started"
            )
        else:
            self._cfg = cfg
        return self

    @property
    def session(self) -> ClientSession:
        if not self._session:
            logger.debug("Configuring shared connection to GraphQL server")

            # Delay checking the environment until we actually need it.
            if not self._params:
                self._params = ConnectParams.from_env()

            if not self._params:
                msg = "No active engine session to connect to"
                raise ClientConnectionError(msg)

            self._session = ClientSession(self._params, self._cfg)
        return self._session

    def is_connected(self) -> bool:
        return self._session is not None and self._session.has_session()

    async def close(self) -> None:
        if self._session:
            await super().close()
            self._session = None

View on GitHub (pinned to 82ba2681db)

Solutions

1. Set DAGGER_SESSION_HOST to the address of a running engine session (start one with `dagger session` or `dagger run`).
2. Or remove the custom-env assumption and let the SDK auto-provision: use `dagger run python yourscript.py` or plain `dagger.Connection()`.
3. If passing ConnectParams explicitly, ensure session_host is set and non-empty.
4. Check that the env var is actually exported in the process (os.environ) and not lost through subprocess/scheduler contexts.

Example fix

// before (shell)
python main.py  # no DAGGER_SESSION_HOST -> error

// after
dagger run python main.py
# or
export DAGGER_SESSION_HOST=$(dagger session --host-only)  # then run the script

import os
if not os.environ.get("DAGGER_SESSION_HOST") and not explicit_params:
    # let SDK auto-provision or fail early with a clear message
    print("No DAGGER_SESSION_HOST; SDK will provision its own engine")

from dagger import ClientConnectionError
try:
    client = dagger.dag
except ClientConnectionError as e:
    raise SystemExit("Run via `dagger run` or set DAGGER_SESSION_HOST") from e

When it happens

Trigger: Creating a ClientConnection with no explicit ConnectParams while DAGGER_SESSION_HOST is unset AND engine provisioning is not possible in that code path; or calling session() on a connection after params resolution failed.

Common situations: CI environments where DAGGER_SESSION_HOST was expected to be set by a `dagger session` step but wasn't; connecting from a subprocess with a scrubbed environment; mixing `dagger run`-provided env into a plain Python process.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• {str(e)}
• engine client: %w
• session attachable conn for client %q was nil
• main client conn %q was nil
• determine current engine version: %w

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/47b1d1c57dd161a2. Report an issue: GitHub.