vxcontrol/pentagi · critical

runtime verification failed: %w

Error message

runtime verification failed: %w

What it means

ExecCommand first verifies the sandbox container is alive by calling dockerClient.IsContainerRunning. If that check itself errors (Docker API unreachable, container ID unknown, context canceled), the call fails with "runtime verification failed: %w" wrapping the underlying Docker error.

Source

Thrown at backend/pkg/tools/terminal.go:206

}

func (t *terminal) ExecCommand(
	ctx context.Context,
	cwd, command string,
	detach bool,
	timeout time.Duration,
) (string, error) {
	containerName := PrimaryTerminalName(t.tenantPrefix, t.flowID)

	cmd := []string{
		"sh",
		"-c",
		command,
	}

	isRunning, err := t.dockerClient.IsContainerRunning(ctx, t.containerLID)
	if err != nil {
		return "", fmt.Errorf("runtime verification failed: %w", err)
	}
	if !isRunning {
		return "", fmt.Errorf("container runtime is not operational")
	}

	if cwd == "" {
		cwd = docker.WorkFolderPathInContainer
	}

	// Format command with working directory and ANSI styling
	styledCommand := fmt.Sprintf("%s $ %s%s%s%s", cwd, ansiColorInputCmd, command, ansiColorReset, ansiLineTerminator)
	_, err = t.tlp.PutMsg(ctx, database.TermlogTypeStdin, styledCommand, t.containerID, t.taskID, t.subtaskID)
	if err != nil {
		return "", fmt.Errorf("failed to put terminal log (stdin): %w", err)
	}

	timeout = t.normalizeExecTimeout(timeout)

View on GitHub (pinned to ea665308ba)

Solutions

1. Inspect the wrapped %w cause with errors.Unwrap or %v to see the actual Docker error
2. Verify the container exists and is up: docker ps / docker inspect <containerLID>
3. Check Docker daemon availability and socket permissions (docker info)
4. Recreate the terminal container if the ID is stale, then retry

Example fix

// before
out, err := term.ExecCommand(ctx, cwd, cmd, false, timeout) // runtime verification failed: ...
// after
if err := term.Ping(ctx); err != nil {
    term.Recreate(ctx) // re-provision sandbox before executing
}
out, err := term.ExecCommand(ctx, cwd, cmd, false, timeout)

if err := dockerClient.Ping(ctx); err != nil {
    return fmt.Errorf("docker unavailable before exec: %w", err)
}
running, err := dockerClient.IsContainerRunning(ctx, containerLID)
if err != nil || !running {
    return fmt.Errorf("terminal container not ready: %w", err)
}

out, err := term.ExecCommand(ctx, cwd, cmd, false, timeout)
if err != nil && strings.HasPrefix(err.Error(), "runtime verification failed:") {
    // transient Docker issue — backoff and retry after checking daemon health
    select {
    case <-time.After(2 * time.Second):
        out, err = term.ExecCommand(ctx, cwd, cmd, false, timeout)
    case <-ctx.Done():
        return ctx.Err()
    }
}

When it happens

Trigger: Calling ExecCommand (directly or via Handle/exec tool) when the Docker daemon is down, the container ID (containerLID) is stale or removed, or the context is canceled/timed out during the Docker API call.

Common situations: Docker daemon restarted or host rebooted; container garbage-collected between flow steps; Docker socket permission issues; network partition to a remote Docker host.

Related errors

• failed to attach file-check exec: %w
• failed to ensure docker network %s: %w
• failed to pull default image '%s': %w
• truncated exec stream: %w
• failed to pull image: %w

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/38a5e436c31ace6f. Report an issue: GitHub.