docker/cli · error

invalid credential spec: value must be prefixed with "config

Error message

invalid credential spec: value must be prefixed with "config://", "file://", or "registry://"

What it means

Raised by credentialSpecOpt.Set when parsing --credential-spec for `docker service create/update`. Credential specs (used for Windows gMSA / Active Directory identity) must name their source with one of three URI-style prefixes: config:// (a swarm config), file:// (a file under the daemon's CredentialSpecs directory), or registry:// (a Windows registry key). Any other prefix or a bare value is rejected.

Source

Thrown at cli/command/service/opts.go:401

		// Therefore, this isn't the definitive location for the value of
		// Config that is passed to the API.
		c.value = &swarm.CredentialSpec{
			Config: val,
		}
		return nil
	case credentialSpecFile:
		c.value = &swarm.CredentialSpec{
			File: val,
		}
		return nil
	case credentialSpecRegistry:
		c.value = &swarm.CredentialSpec{
			Registry: val,
		}
		return nil
	default:
		c.value = &swarm.CredentialSpec{}
		return errors.New(`invalid credential spec: value must be prefixed with "config://", "file://", or "registry://"`)
	}
}

func (*credentialSpecOpt) Type() string {
	return "credential-spec"
}

func (c *credentialSpecOpt) String() string {
	return c.source
}

func (c *credentialSpecOpt) Value() *swarm.CredentialSpec {
	return c.value
}

func resolveNetworkID(ctx context.Context, apiClient client.NetworkAPIClient, networkIDOrName string) (string, error) {
	res, err := apiClient.NetworkInspect(ctx, networkIDOrName, client.NetworkInspectOptions{Scope: "swarm"})
	if err != nil {

View on GitHub (pinned to e9452d6e78)

Solutions

1. Prefix the value correctly, e.g. `--credential-spec 'file://spec.json'` with the file placed in the daemon's CredentialSpecs directory (C:\ProgramData\docker\CredentialSpecs on Windows).
2. To source from a swarm config, create it first (`docker config create credspec spec.json`) and use `--credential-spec 'config://credspec'`.
3. Use `registry://<key>` if the spec is stored in the Windows registry under HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs.

Example fix

# before
docker service create --credential-spec C:\\specs\\gmsa.json myimage
# after
docker service create --credential-spec 'file://gmsa.json' myimage  # file lives in daemon's CredentialSpecs dir

When it happens

Trigger: `docker service create --credential-spec ./spec.json ...` or `--credential-spec mycred` — any value not starting with config://, file://, or registry://; also typos like files:// or a missing prefix in compose `credential_spec` translation scripts.

Common situations: Windows Swarm gMSA setups where operators pass a raw host path to the JSON credential spec instead of `file://name.json` (the file:// form is relative to the daemon's CredentialSpecs directory, not an arbitrary path), or migrating from docker run's --security-opt syntax which differs.

Related errors

• placement preference must be of the format "<strategy>=<arg>
• error reading from STDIN: data is empty
• secret file is required
• got wrong object to inspect
• --format is incompatible with human friendly format

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/434314a7389a98b2.json. Report an issue: GitHub.