What causes "opening output file: %v" in caddyserver/caddy?

Create the parent directory: mkdir -p $(dirname )

opening output file: %v

Error message

opening output file: %v

What it means

cmdExportStorage ('caddy storage export') failed at os.Create of the --output file (unless '-' was passed for stdout). Keys were already listed from storage, but nothing has been written yet. Standard os.PathError causes: directory does not exist, permission denied, or a path that is a directory.

Source

Thrown at cmd/storagefuncs.go:183

		}
	} else {
		stor = caddy.DefaultStorage
	}

	// enumerate all keys
	keys, err := stor.List(ctx, "", true)
	if err != nil {
		return caddy.ExitCodeFailedStartup, err
	}

	// setup output
	var f *os.File
	if exportStorageCmdOutputFlag == "-" {
		f = os.Stdout
	} else {
		f, err = os.Create(exportStorageCmdOutputFlag)
		if err != nil {
			return caddy.ExitCodeFailedStartup, fmt.Errorf("opening output file: %v", err)
		}
		defer f.Close()
	}

	// `IsTerminal: true` keys hold the values we
	// care about, write them out
	tw := tar.NewWriter(f)
	for _, k := range keys {
		info, err := stor.Stat(ctx, k)
		if err != nil {
			if errors.Is(err, fs.ErrNotExist) {
				caddy.Log().Warn(fmt.Sprintf("key: %s removed while export is in-progress", k))
				continue
			}
			return caddy.ExitCodeFailedQuit, err
		}

		if info.IsTerminal {

View on GitHub (pinned to 50e54ee279)

Solutions

Create the parent directory: mkdir -p $(dirname <output.tar>)
Choose a writable location or run with sudo as the storage-owning user
Ensure --output names a file, not a directory
Or export to stdout: --output - > /path/storage.tar

Example fix

# before
caddy storage export --config caddy.json --output /var/backups/caddy/storage.tar
# error: opening output file: open /var/backups/caddy/storage.tar: no such file or directory

# after
mkdir -p /var/backups/caddy
caddy storage export --config caddy.json --output /var/backups/caddy/storage.tar

Defensive patterns

Strategy: validation

Validate before calling

OUT=/var/backups/caddy/storage.tar
mkdir -p "$(dirname "$OUT")" && [ -w "$(dirname "$OUT")" ] || echo 'output dir missing/unwritable'

Prevention

mkdir -p the output directory before exporting (os.Create will not create parents)
Use absolute output paths and confirm writability in scripts
Use --output - piped to a file when directory setup is inconvenient

When it happens

Trigger: Output path in a nonexistent directory (os.Create does not create parents); unwritable destination; --output pointing at a directory; invalid path characters.

Common situations: Exporting to /var/backups/caddy/storage.tar before creating /var/backups/caddy; unprivileged user writing to a root-owned dir; typo'd path.

Related errors

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