vxcontrol/pentagi · error

target container is not operational

Error message

target container is not operational

What it means

The write-path sibling of 'container runtime is not operational': after a successful IsContainerRunning query, writeFileToContainer refuses to write if the flow's terminal container reports a non-running state. Unlike 958, Docker answered fine — the container is simply exited/stopped, so the tar-based PutToArchive would fail.

Source

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

	if err != nil {
		return "", fmt.Errorf("failed to put terminal log (write file cmd): %w", err)
	}

	return fmt.Sprintf("Successfully wrote %d bytes to %s", len(content), path), nil
}

// writeFileToContainer copies content into the flow's container at path,
// overwriting it. It performs no terminal-log writes; WriteFile and EditFile
// each log their own, differently-worded, success message.
func (t *terminal) writeFileToContainer(ctx context.Context, flowID int64, path, content string) error {
	containerName := PrimaryTerminalName(t.tenantPrefix, flowID)

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

	// Docker SDK requires TAR format for file transfer
	tarBuffer := &bytes.Buffer{}
	archiveWriter := tar.NewWriter(tarBuffer)
	defer archiveWriter.Close()

	filename := filepath.Base(path)
	fileDescriptor := &tar.Header{
		Name: filename,
		Mode: 0600,
		Size: int64(len(content)),
	}
	err = archiveWriter.WriteHeader(fileDescriptor)
	if err != nil {
		return fmt.Errorf("tar archive header generation failed: %w", err)
	}

View on GitHub (pinned to ea665308ba)

Solutions

1. Restart the container: `docker start <container>` or let the flow lifecycle re-create the primary terminal container, then retry the write
2. Check the exit reason: `docker inspect -f '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}}' <container>` and `docker logs`
3. Set a restart policy (e.g. unless-stopped) or ensure the platform's container manager keeps the terminal container alive for the flow duration
4. In the caller, check IsContainerRunning before writing and either restart the container or fail fast with a user-actionable message

Example fix

// before
_, err := tool.WriteFile(ctx, flowID, content, "/tmp/results.json")
// after
if running, _ := dockerClient.IsContainerRunning(ctx, containerLID); !running {
    if err := dockerClient.StartContainer(ctx, containerLID); err != nil {
        return fmt.Errorf("terminal container not running and restart failed: %w", err)
    }
}
_, err := tool.WriteFile(ctx, flowID, content, "/tmp/results.json")

running, err := dockerClient.IsContainerRunning(ctx, containerLID)
if err != nil {
    return fmt.Errorf("cannot verify container: %w", err)
}
if !running {
    if err := dockerClient.StartContainer(ctx, containerLID); err != nil {
        return fmt.Errorf("container stopped and could not be started: %w", err)
    }
}

func containerOperational(inspect types.ContainerJSON) bool {
    return inspect.State != nil && inspect.State.Running && !inspect.State.Dead
}

_, err := tool.WriteFile(ctx, flowID, content, path)
if err != nil && strings.Contains(err.Error(), "target container is not operational") {
    // restart or recreate the terminal container, then retry once
    _, err = tool.WriteFile(ctx, flowID, content, path)
}

When it happens

Trigger: WriteFile or EditFile invoked while the flow's terminal container has exited: sandbox container finished/crashed, `docker stop` issued, host rebooted without restart policy, or the flow was cleaned up while the tool call was still in flight.

Common situations: Agent attempts to persist results after its sandbox was torn down at flow end; container OOM-killed or entrypoint exited so Docker set state=exited; restart policy set to `no` so it never comes back after a daemon restart.

Related errors

• container shutdown failed: %w
• failed to stop container: %w
• failed to remove container: %w
• failed to create list exec for '%s': %w
• tar archive header generation failed: %w

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