docker/cli · error · invalidParameter

invalid context: no metadata found

Error message

invalid context: no metadata found

What it means

Returned by importTar after iterating every entry in a tarball: if no entry named meta.json (the metaFile) was found, the archive has no context metadata and cannot be imported. Docker contexts require a meta.json file describing endpoints and configuration.

Solutions

1. Re-export the context from the original host with docker context export and import that file.
2. Inspect the tarball with tar -tf <file> and confirm a top-level 'meta.json' entry exists.
3. If the metadata entry is nested under a subdirectory, repackage the archive so meta.json sits at the archive root.

Example fix

// before: docker context import myctx < random.tar  # no meta.json inside
// after:  docker context export orig; docker context import myctx < orig.dockercontext

// Pre-check that a tar archive contains meta.json before importing
func tarHasMeta(r io.Reader) (bool, error) {
	tr := tar.NewReader(r)
	for {
		hdr, err := tr.Next()
		if err == io.EOF { return false, nil }
		if err != nil { return false, err }
		if hdr.Typeflag == tar.TypeReg && path.Clean(hdr.Name) == "meta.json" {
			return true, nil
		}
	}
}

When it happens

Trigger: Calling store.Import on a tar stream that lacks a 'meta.json' entry — e.g. importing an arbitrary tarball, a truncated/corrupt export, or an archive whose metadata entry was renamed or placed in a subdirectory.

Common situations: Importing a tarball that was not produced by docker context export; a partial file transfer that dropped the metadata entry; manually editing the archive and deleting meta.json; using the wrong file as the import source.

Related errors

• %s: %w
• context metadata is not a valid DockerContext
• cannot find docker endpoint in context
• read exceeds the defined limit
• unexpected context file

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

Appendix: source

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

			if err != nil {
				return err
			}
			if err := s.CreateOrUpdate(meta); err != nil {
				return err
			}
			importedMetaFile = true
		} else if strings.HasPrefix(hdr.Name, "tls/") {
			data, err := io.ReadAll(tr)
			if err != nil {
				return err
			}
			if err := importEndpointTLS(&tlsData, hdr.Name, data); err != nil {
				return err
			}
		}
	}
	if !importedMetaFile {
		return invalidParameter(errors.New("invalid context: no metadata found"))
	}
	return s.ResetTLSMaterial(name, &tlsData)
}

func importZip(name string, s Writer, reader io.Reader) error {
	body, err := io.ReadAll(&limitedReader{R: reader, N: maxAllowedFileSizeToImport})
	if err != nil {
		return err
	}
	zr, err := zip.NewReader(bytes.NewReader(body), int64(len(body)))
	if err != nil {
		return err
	}
	tlsData := ContextTLSData{
		Endpoints: map[string]EndpointTLSData{},
	}

	var importedMetaFile bool

View on GitHub (pinned to 4f84911bfe)