caddyserver/caddy · error

reading archive: %v

Error message

reading archive: %v

What it means

During 'caddy storage import', tar.Reader.Next() failed with something other than io.EOF while advancing to the next archive entry. The input opened fine but is not a valid (uncompressed) tar stream — most often it is gzip-compressed (the code applies no decompression), truncated, or not a tar at all.

Source

Thrown at cmd/storagefuncs.go:118

	if importStorageCmdImportFile == "-" {
		f = os.Stdin
	} else {
		f, err = os.Open(importStorageCmdImportFile)
		if err != nil {
			return caddy.ExitCodeFailedStartup, fmt.Errorf("opening input file: %v", err)
		}
		defer f.Close()
	}

	// store each archive element
	tr := tar.NewReader(f)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			break
		}
		if err != nil {
			return caddy.ExitCodeFailedQuit, fmt.Errorf("reading archive: %v", err)
		}

		b, err := io.ReadAll(tr)
		if err != nil {
			return caddy.ExitCodeFailedQuit, fmt.Errorf("reading archive: %v", err)
		}

		err = stor.Store(ctx, hdr.Name, b)
		if err != nil {
			return caddy.ExitCodeFailedQuit, fmt.Errorf("reading archive: %v", err)
		}
	}

	fmt.Println("Successfully imported storage")
	return caddy.ExitCodeSuccess, nil
}

func cmdExportStorage(fl Flags) (int, error) {

View on GitHub (pinned to 50e54ee279)

Solutions

1. If compressed, decompress first: gunzip -c storage.tar.gz > storage.tar, then import the plain tar
2. Verify integrity: tar -tf storage.tar should list entries without errors
3. Re-export from the source storage if the archive is truncated
4. Stream directly between instances: caddy storage export ... --output - | caddy storage import ... --input -

Example fix

# before
caddy storage import --config caddy.json --input storage.tar.gz
# error: reading archive: gzip: invalid header (or tar format error)

# after
gunzip -c storage.tar.gz | caddy storage import --config caddy.json --input -

# verify the archive is a plain, readable tar before importing
tar -tf storage.tar >/dev/null && echo ok || echo 'not a valid tar (gzip? corrupt?)'
# decompress if needed: gunzip -c storage.tar.gz > storage.tar

When it happens

Trigger: Feeding a .tar.gz to --input (the reader expects plain tar); a tar truncated by an interrupted 'caddy storage export'; passing an arbitrary file (JSON config, zip) as --input.

Common situations: Admin compresses exports to save space (gzip -9 storage.tar) then imports without decompressing; scp transfer cut short; exporting to '-' piped through a tool that mangled the bytes.

Related errors

• opening input file: %v
• writing archive: %v
• WebSocket connections aren't allowed.
• Disabling same-origin restrictions is not allowed.
• Buggy browser is sending null Origin header.

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