docker/cli · error

refusing to load key from

Error message

refusing to load key from %s: %w

What it means

In loadPrivKey (key_load.go:62-65), getPrivKeyBytesFromPath(keyPath) failed and is wrapped as 'refusing to load key from <path>'. getPrivKeyBytesFromPath (key_load.go:73-91) stats the file, checks the permission mask on non-Windows, opens it read-only, and reads all bytes - so this wraps any of: file not found, permission check failure (others can read/write it), open error, or read error.

Solutions

1. Verify the file exists and is readable: ls -l <keyfile> and cat <keyfile> | head -c 20.
2. Use an absolute path to avoid cwd issues.
3. Check ownership/permissions: chown/chmod so the current user can read it (but keep it 0600 - see error 557).
4. Confirm the path is a regular file, not a directory.
5. Inspect the wrapped %w error for the exact os error (ENOENT, EACCES, etc.).

Example fix

# before
docker trust key load ~/wrong-name.key  # typo
docker trust key load ./priv.key  # wrong cwd
# after
docker trust key load /home/user/keys/priv.key

// Validate the key file path is readable before loading.
func ensureKeyFileReadable(path string) error {
    info, err := os.Stat(path)
    if err != nil {
        return fmt.Errorf("refusing to load key from %s: %w", path, err)
    }
    if info.IsDir() {
        return fmt.Errorf("refusing to load key from %s: not a file", path)
    }
    f, err := os.Open(path)
    if err != nil {
        return fmt.Errorf("refusing to load key from %s: %w", path, err)
    }
    f.Close()
    return nil
}

keyBytes, err := getPrivKeyBytesFromPath(keyPath)
if err != nil {
    return fmt.Errorf("refusing to load key from %s: %w", keyPath, err)
}

When it happens

Trigger: The KEYFILE path does not exist; the file exists but is openable only by another user; the file permissions allow group/other read or write (fails the nonOwnerReadWriteMask check -> but that has its own dedicated message at 557, so this wrap is for the os.Stat/os.OpenFile/io.ReadAll errors); I/O error reading the file.

Common situations: Typo in the key file path; relative path from a different cwd; file deleted between check and read; running as a user without read permission; NFS/filesystem hiccup; path is a directory not a file.

Related errors

• public key path does not exist
• public key file already exists
• failed to generate key for
• failed to write public key to
• error importing key from

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

Appendix: source

Thrown at cmd/docker-trust/trust/key_load.go:64

func loadPrivKey(streams command.Streams, keyPath string, options keyLoadOptions) error {
	// validate the key name if provided
	if options.keyName != "" && !validKeyName(options.keyName) {
		return fmt.Errorf("key name \"%s\" must start with lowercase alphanumeric characters and can include \"-\" or \"_\" after the first character", options.keyName)
	}
	trustDir := trust.GetTrustDirectory()
	keyFileStore, err := storage.NewPrivateKeyFileStorage(trustDir, notary.KeyExtension)
	if err != nil {
		return err
	}
	privKeyImporters := []trustmanager.Importer{keyFileStore}

	_, _ = fmt.Fprintf(streams.Out(), "Loading key from \"%s\"...\n", keyPath)

	// Always use a fresh passphrase retriever for each import
	passRet := trust.GetPassphraseRetriever(streams.In(), streams.Out())
	keyBytes, err := getPrivKeyBytesFromPath(keyPath)
	if err != nil {
		return fmt.Errorf("refusing to load key from %s: %w", keyPath, err)
	}
	if err := loadPrivKeyBytesToStore(keyBytes, privKeyImporters, keyPath, options.keyName, passRet); err != nil {
		return fmt.Errorf("error importing key from %s: %w", keyPath, err)
	}
	_, _ = fmt.Fprintln(streams.Out(), "Successfully imported key from", keyPath)
	return nil
}

func getPrivKeyBytesFromPath(keyPath string) ([]byte, error) {
	if runtime.GOOS != "windows" {
		fileInfo, err := os.Stat(keyPath)
		if err != nil {
			return nil, err
		}
		if fileInfo.Mode()&nonOwnerReadWriteMask != 0 {
			return nil, fmt.Errorf("private key file %s must not be readable or writable by others", keyPath)
		}
	}

View on GitHub (pinned to 4f84911bfe)