caddyserver/caddy · error

unable to download file: %v

Error message

unable to download file: %v

What it means

io.Copy from the HTTP response body to the destination file failed mid-stream. The connection was established and the status was OK, but the transfer broke partway — network reset, proxy timeout, or the server closing the connection. The deferred restore returns the original binary, so this is recoverable by retrying.

Source

Thrown at cmd/packagesfuncs.go:331

		}
		pluginPkgs[mod.goModule.Path] = pluginPackage{Version: mod.goModule.Version, Path: mod.goModule.Path}
	}
	return pluginPkgs, nil
}

func writeCaddyBinary(path string, body *io.ReadCloser, fileInfo os.FileInfo) error {
	l := caddy.Log()
	destFile, err := os.OpenFile(path, os.O_RDWR|os.O_CREATE|os.O_TRUNC, fileInfo.Mode())
	if err != nil {
		return fmt.Errorf("unable to open destination file: %v", err)
	}
	defer destFile.Close()

	l.Info("downloading binary", zap.String("destination", path))

	_, err = io.Copy(destFile, *body)
	if err != nil {
		return fmt.Errorf("unable to download file: %v", err)
	}

	err = destFile.Sync()
	if err != nil {
		return fmt.Errorf("syncing downloaded file to device: %v", err)
	}

	return nil
}

const downloadPath = "https://caddyserver.com/api/download"

type pluginPackage struct {
	Version string
	Path    string
}

func (p pluginPackage) String() string {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Simply retry 'caddy upgrade' — the original binary was restored automatically
2. If behind a proxy, raise its read/idle timeouts or use a wired/stable connection
3. Check for packet loss or MTU issues on VPN tunnels
4. As a fallback, download a matching custom build URL with curl --retry and replace the binary manually

When it happens

Trigger: Long download interrupted by connection reset; idle-timeout on a proxy or NAT gateway killing the stream; flaky Wi-Fi/VPN; server-side connection drop during a slow custom build (builds can take a while before streaming starts).

Common situations: Upgrading on an unstable connection; slow plugin compilation causing intermediary load balancers to time out; mobile/tethered networks.

Related errors

• download failed: %v
• secure request failed: %v
• download and error decoding failed: HTTP %d: %v
• loading dynamic config from %T: %v
• server responded with HTTP %d

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/50d5d9b1e1849f07. Report an issue: GitHub.