docker/cli · error

unexpected context file

Error message

unexpected context file

What it means

Returned by isValidFilePath during context archive import: an entry's path must be either the metadata file (metaFile) or live under the 'tls/' prefix. Any other file is rejected because a context archive may only contain metadata and TLS material, preventing arbitrary file writes outside the expected layout.

Solutions

1. Re-export the context from a valid source so the archive contains only meta.json and tls/* entries.
2. Manually remove non-conforming entries from the archive before importing.
3. Ensure TLS files are placed under the 'tls/<endpoint>/' path within the archive.

// Reject archives with unexpected entries before importing.
for _, e := range entries {
    if e != metaFile && !strings.HasPrefix(e, "tls/") {
        return fmt.Errorf("unexpected file in archive: %s", e)
    }
}

func isAllowedContextPath(p string) bool {
    return p == metaFile || strings.HasPrefix(p, "tls/")
}

When it happens

Trigger: Importing a tar/zip archive that contains files at the root or in unexpected directories (e.g. 'readme.txt', 'certs/ca.pem' instead of 'tls/...'). A tampered or hand-built archive including extra entries.

Common situations: A user zips a whole folder including non-context files. An export tool adds unexpected artifacts. Path manipulation in a crafted archive.

Related errors

• unexpected path format
• unexpected '\\' in path
• %s: %w
• read exceeds the defined limit
• archive format is invalid

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/560fdd6ef94e7f4e. Report an issue: GitHub.

Appendix: source

Thrown at cli/context/store/store.go:373

	// Buffered reader will not advance the buffer, needed to determine content type
	r := bufio.NewReader(reader)

	importContentType, err := getImportContentType(r)
	if err != nil {
		return err
	}
	switch importContentType {
	case zipType:
		return importZip(name, s, r)
	default:
		// Assume it's a TAR (TAR does not have a "magic number")
		return importTar(name, s, r)
	}
}

func isValidFilePath(p string) error {
	if p != metaFile && !strings.HasPrefix(p, "tls/") {
		return errors.New("unexpected context file")
	}
	if path.Clean(p) != p {
		return errors.New("unexpected path format")
	}
	if strings.Contains(p, `\`) {
		return errors.New(`unexpected '\' in path`)
	}
	return nil
}

func importTar(name string, s Writer, reader io.Reader) error {
	tr := tar.NewReader(&limitedReader{R: reader, N: maxAllowedFileSizeToImport})
	tlsData := ContextTLSData{
		Endpoints: map[string]EndpointTLSData{},
	}
	var importedMetaFile bool
	for {
		hdr, err := tr.Next()

View on GitHub (pinned to 4f84911bfe)