vxcontrol/pentagi · error

failed to attach file-check exec: %w

Error message

failed to attach file-check exec: %w

What it means

This error wraps a failure from Docker's ContainerExecAttach call when the flowToolsExecutor tries to attach to a created exec instance inside the sandbox container to run a file-check command. It is thrown because, although the exec instance was created successfully, the streaming HTTP hijack (attach) to that instance failed. The wrapped error carries the underlying Docker client/daemon cause.

Source

Thrown at backend/pkg/tools/tools.go:667

	cmd = append(cmd, "sh", "-c",
		`for f in "$@"; do [ -f "$f" ] || printf '%s\n' "$f"; done`, "--")
	for _, e := range entries {
		cmd = append(cmd, e.containerPath)
	}

	containerName := PrimaryTerminalName(fte.cfg.TenantPrefix(), fte.flowID)
	createResp, err := fte.docker.ContainerExecCreate(ctx, containerName, client.ExecCreateOptions{
		Cmd:          cmd,
		AttachStdout: true,
		AttachStderr: true,
	})
	if err != nil {
		return nil, fmt.Errorf("failed to create file-check exec: %w", err)
	}

	resp, err := fte.docker.ContainerExecAttach(ctx, createResp.ID, client.ExecAttachOptions{})
	if err != nil {
		return nil, fmt.Errorf("failed to attach file-check exec: %w", err)
	}
	output, readErr := io.ReadAll(resp.Reader)
	resp.Close()
	if readErr != nil {
		return nil, fmt.Errorf("failed to read file-check output: %w", readErr)
	}
	inspect, err := fte.docker.ContainerExecInspect(ctx, createResp.ID)
	if err != nil {
		return nil, fmt.Errorf("failed to inspect file-check exec: %w", err)
	}
	if inspect.ExitCode != 0 {
		return nil, fmt.Errorf("file-check exec failed with exit code %d: %s", inspect.ExitCode, strings.TrimSpace(string(output)))
	}

	byContainerPath := make(map[string]fileSyncEntry, len(entries))
	for _, e := range entries {
		byContainerPath[e.containerPath] = e
	}

View on GitHub (pinned to ea665308ba)

Solutions

1. Check that the target container is running (docker ps) at the moment of the exec; recreate or restart the flow's sandbox container
2. Verify the Docker daemon is reachable: docker info from the backend container; check DOCKER_HOST and socket mount
3. Inspect wrapped error in logs: if 'context canceled', the flow/HTTP request was aborted — handle cancellation instead of retrying
4. Add retry with backoff for transient attach failures, or check container state before attaching

Example fix

// before
resp, err := fte.docker.ContainerExecAttach(ctx, createResp.ID, client.ExecAttachOptions{})
if err != nil {
	return nil, fmt.Errorf("failed to attach file-check exec: %w", err)
}
// after
if err := ctx.Err(); err != nil {
	return nil, fmt.Errorf("file-check canceled before attach: %w", err)
}
resp, err := fte.docker.ContainerExecAttach(ctx, createResp.ID, client.ExecAttachOptions{})
if err != nil {
	return nil, fmt.Errorf("failed to attach file-check exec: %w", err)
}

// before creating the exec
info, err := cli.ContainerInspect(ctx, containerID)
if err != nil || !info.State.Running {
	return fmt.Errorf("container %s not running: %v", containerID, err)
}
if err := ctx.Err(); err != nil {
	return err
}

var ae *dockererr // inspect wrapped cause
err := runFileCheck(ctx)
if err != nil {
	if errors.Is(err, context.Canceled) {
		// do not retry: caller aborted
		return err
	}
	if strings.Contains(err.Error(), "failed to attach") {
		// transient: retry with backoff
		err = retry.Do(func() error { return runFileCheck(ctx) }, retry.Attempts(2))
	}
}

When it happens

Trigger: fte.docker.ContainerExecAttach(ctx, createResp.ID, client.ExecAttachOptions{}) fails: container stopped/removed between create and attach, Docker daemon unreachable or restarting, context canceled, or the exec ID is invalid.

Common situations: Agent tool executes file checks while the target sandbox container is being torn down mid-flow; Docker daemon restarts under load; network interruption between the API server and dockerd (DOCKER_HOST socket/HTTP); flow context canceled when the user aborts the flow while a check is in flight.

Related errors

• runtime verification failed: %w
• failed to create exec process: %w
• failed to attach to exec process: %w
• failed to inspect exec process: %w
• failed to inspect file-check exec: %w

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