argoproj/argo-workflows · error

failed to stage files: %w

Error message

failed to stage files: %w

What it means

runSupervisorPreMain wraps failures of the StageFiles stage as "failed to stage files". StageFiles materializes file-type inputs (e.g. artifact files or staged manifest files) into the pod before the main container starts; failure aborts pre-main via short-circuit, so the main container never becomes ready.

Source

Thrown at cmd/argoexec/commands/supervisor.go:147

func supervisorPreMain(ctx context.Context, wfExecutor *wfexecutor.WorkflowExecutor) error {
	// Zero umask so files/dirs created here are accessible to main when it
	// runs as a different uid. The legacy init container does the same.
	osspecific.AllowGrantingAccessToEveryone()

	// A stale marker from a prior attempt needs no explicit cleanup: the
	// heartbeat's initial RUNNING write (startStatusHeartbeat, before we get
	// here) has already overwritten it with a fresh mtime.
	return runSupervisorPreMain(ctx, wfExecutor, inputArtifactPluginNames())
}

// runSupervisorPreMain is the testable core of supervisorPreMain. Takes
// the plugin name list explicitly so tests don't have to mutate env vars.
func runSupervisorPreMain(ctx context.Context, stages preMainStages, pluginNames []wfv1.ArtifactPluginName) error {
	if err := stages.WriteTemplate(); err != nil {
		return fmt.Errorf("failed to write template: %w", err)
	}
	if err := stages.StageFiles(ctx); err != nil {
		return fmt.Errorf("failed to stage files: %w", err)
	}

	g, gctx := errgroup.WithContext(ctx)
	g.Go(func() error {
		if err := stages.LoadArtifactsWithoutPlugins(gctx); err != nil {
			return fmt.Errorf("failed to load non-plugin input artifacts: %w", err)
		}
		return nil
	})
	for _, name := range pluginNames {
		g.Go(func() error {
			if err := stages.LoadArtifactsFromPlugin(gctx, name); err != nil {
				return fmt.Errorf("failed to load input artifacts from plugin %q: %w", name, err)
			}
			return nil
		})
	}
	return g.Wait()

View on GitHub (pinned to 35bff19146)

Solutions

1. Inspect the wrapped cause for the concrete staging error (ENOENT/EACCES/ENOSPC)
2. Verify the source paths referenced by the template inputs exist in the pod
3. Ensure /var/run/argo (or the stage target dir) is writable and has free space
4. Re-run the workflow node after fixing the volume mount or template paths

// verify staged sources exist and target dir is writable:
// kubectl exec <pod> -c main -- ls -l <staged-source-paths>
// kubectl exec <pod> -c main -- test -w /var/run/argo

if err := stages.StageFiles(ctx); err != nil {
    return fmt.Errorf("failed to stage files: %w", err)
}
// caller: unwrap to distinguish missing source (ENOENT) vs permission (EACCES)

When it happens

Trigger: supervisorPreMain → runSupervisorPreMain where the StageFiles stage returns an error — destination directory not writable, source file missing, or a copy failure during staging.

Common situations: Init-less workflows with input artifacts staged as files where the /var/run/argo mount is broken or full; wrong paths in template inputs; permissions preventing the supervisor from creating staged files.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• failed to write template: %w
• failed to write initial status marker: %w
• %w
• failed to load non-plugin input artifacts: %w
• failed to load input artifacts from plugin %q: %w

AI-assisted analysis of argoproj/argo-workflows@35bff19146 (2026-09-03). Data as JSON: /api/errors/bcff9c94fa1813d3. Report an issue: GitHub.