gastownhall/beads · error

dolt: credential from %s is not an identity; refusing to pre

Error message

dolt: credential from %s is not an identity; refusing to present it as the connection username

What it means

A deliberate fail-closed guard in ApplyGatewayCredential: gateway credentials are presented AS the DSN username, so a credential whose Kind is not creds.KindIdentity must never be placed in the connection username slot. The error names cred.Source so the operator knows which credential source produced the rejected token.

Source

Thrown at internal/storage/dolt/gateway_credential.go:48

func ApplyGatewayCredential(ctx context.Context, fileCfg *configfile.Config, cfg *Config) (bool, error) {
	if cfg.ServerUser != "" {
		return false, nil
	}
	cred, ok, err := creds.ResolveLadder(ctx, creds.CommandSource{
		Command: fileCfg.GetDoltCredentialCommand(),
		Kind:    creds.KindIdentity,
		Label:   "BEADS_DOLT_CREDENTIAL_COMMAND",
	})
	if err != nil {
		return false, err
	}
	if !ok {
		return false, nil
	}
	// Defense in depth: the token is presented AS the username, so a non-identity
	// credential must never reach this slot.
	if cred.Kind != creds.KindIdentity {
		return false, fmt.Errorf("dolt: credential from %s is not an identity; refusing to present it as the connection username", cred.Source)
	}
	// The token becomes the DSN username; the go-sql-driver grammar has no escaping for
	// the user field, so a ':' '@' or '/' would silently mis-split it into user/password.
	// Reject rather than connect with a mangled identity. (JWTs are base64url + '.', safe.)
	if strings.ContainsAny(cred.Value, ":@/") {
		return false, fmt.Errorf("dolt: credential from %s contains a character (:, @, or /) that cannot be placed in the connection username", cred.Source)
	}
	// cred.Username (a dynamic user/password pair) is meaningless here: the token IS the
	// username. Ignored deliberately.
	cfg.ServerUser = cred.Value
	cfg.Gateway = true
	cfg.DisableAutoStart = true
	return true, nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Configure the credential source to produce an identity-kind credential for the gateway
2. Check which source (cred.Source) is misconfigured and fix its credential type
3. Verify with the creds package that the resolved credential has Kind == KindIdentity before applying
4. If this comes from a preset, correct the preset definition to reference the identity credential

Example fix

// before
cred := loadCredential("gateway-token") // Kind: password
ok, err := ApplyGatewayCredential(cfg, cred)
// after
cred := loadCredential("gateway-identity") // Kind: identity
if cred.Kind != creds.KindIdentity {
	return fmt.Errorf("gateway requires an identity credential, got %s", cred.Kind)
}
ok, err := ApplyGatewayCredential(cfg, cred)

func isIdentityCred(c creds.Credential) bool { return c.Kind == creds.KindIdentity }
if !isIdentityCred(cred) {
	return fmt.Errorf("gateway needs identity credential, got kind %q from %s", cred.Kind, cred.Source)
}

func isIdentityCredential(c creds.Credential) bool {
	return c.Kind == creds.KindIdentity
}

ok, err := ApplyGatewayCredential(cfg, cred)
if err != nil && strings.Contains(err.Error(), "is not an identity") {
	// fix the credential source, don't retry with same cred
}

When it happens

Trigger: ApplyGatewayCredential loads a credential (from command, JSON envelope, preset, etc.) whose Kind is not KindIdentity — e.g. a raw API token or password-type credential — and tries to apply it to the Dolt gateway connection config.

Common situations: Misconfigured credential store returning the wrong credential kind for the gateway; operator pointing the gateway at a password/token credential instead of an identity credential; version change altering credential Kind classification.

Related errors

• dolt: credential from %s contains a character (:, @, or /) t
• no Dolt remote is configured, and bd will not adopt one with
• resolving dolt credential command: %w
• refusing to write unexpected column %q of %s: %w
• multiple .doltcfg directories detected

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/c4c5ad12de5b864e. Report an issue: GitHub.