docker/cli · error

unexpected path format

Error message

unexpected path format

What it means

Returned by isValidFilePath when path.Clean(p) != p, i.e. the entry path is not in canonical form (contains redundant slashes, '.' or '..' segments, or trailing slashes). Canonicalizing during import prevents path-traversal and duplicate/ambiguous file placement; only already-clean paths are accepted.

Solutions

1. Recreate the archive with normalized entry paths (no '..', '.', or double slashes).
2. Use 'docker context export' on a valid context to produce a well-formed archive.
3. Inspect entries with 'tar -tf archive' or 'unzip -l' and fix any non-canonical paths.

if path.Clean(p) != p {
    return fmt.Errorf("path %q is not canonical; reject to prevent traversal", p)
}

func isCanonicalPath(p string) bool { return path.Clean(p) == p }

When it happens

Trigger: An archive entry whose name is like 'tls/../tls/ca.pem', 'tls//ca.pem', './meta.json', or 'tls/./ca.pem'. Crafted archives attempting directory traversal via '..' segments.

Common situations: A malicious or buggy archive producer emits non-canonical paths. Attempting path traversal to escape the context directory. Tar entries created with non-normalized path separators.

Related errors

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

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

Appendix: source

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

	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()
		if err == io.EOF {
			break
		}

View on GitHub (pinned to 4f84911bfe)