vxcontrol/pentagi · error

file-check exec failed with exit code %d: %s

Error message

file-check exec failed with exit code %d: %s

What it means

This error reports that the file-check command executed inside the container finished with a nonzero exit code, and includes the command's captured stdout/stderr. Unlike the other file-check errors this is an application-level result: Docker worked, but the check script signaled failure (e.g. missing file, checksum mismatch, permission error).

Source

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

	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
	}

	var missing []fileSyncEntry
	for _, line := range strings.Split(string(output), "\n") {
		line = strings.TrimSpace(line)
		if line == "" {
			continue
		}
		if e, ok := byContainerPath[line]; ok {
			missing = append(missing, e)
		}
	}

View on GitHub (pinned to ea665308ba)

Solutions

  1. Read the included command output in the error message — it states exactly why the check failed
  2. Diff actual container state against expected entries (docker exec <container> ls -la <path>) to find the missing/changed file
  3. Verify the file-check script was synced and is executable in the container; exit 127/126 means not found / not executable
  4. Re-sync or re-upload the affected files and retry the flow step

Example fix

// before
if inspect.ExitCode != 0 {
	return nil, fmt.Errorf("file-check exec failed with exit code %d: %s", inspect.ExitCode, strings.TrimSpace(string(output)))
}
// after
if inspect.ExitCode != 0 {
	return nil, fmt.Errorf("file-check exec failed with exit code %d: %s", inspect.ExitCode, strings.TrimSpace(string(output)))
}
// fix on the caller side: surface the captured output to the agent/user instead of retrying blindly
Defensive patterns

Strategy: validation

Validate before calling

// pre-validate files client-side before running the in-container check
for _, e := range entries {
	if _, err := os.Stat(e.hostPath); err != nil {
		return fmt.Errorf("missing source file %s: %w", e.hostPath, err)
	}
}
// also ensure the check command exists in the image:
// docker exec <container> which -a sh

Try / catch

err := runFileCheck(ctx)
if err != nil {
	var exitErr *ExitCodeError // or match on the message prefix
	if strings.HasPrefix(err.Error(), "file-check exec failed with exit code") {
		// deterministic result: surface output, do not blind-retry
		return fmt.Errorf("sync verification failed, inspect container state: %w", err)
	}
	return err
}

Prevention

When it happens

Trigger: inspect.ExitCode != 0 after the file-check exec runs, e.g. the check shell command exits 1 because a file that should exist in the container is missing, checksums differ, or the check script itself is not executable/found (exit 127).

Common situations: Container filesystem diverged from the expected upload state (file deleted or modified inside sandbox); file-check script path wrong or not synced; permissions/ownership changed by commands run earlier in the flow; check command uses a shell binary not present in the image.

Related errors

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