gravitational/teleport · error

unexpected escaped character %q: %s

Error message

unexpected escaped character %q: %s

What it means

Backslash escapes are limited to the RFC 2253 specials (',' '=' '+' '<' '>' '#' ';' '\' '"') and space. Hex escapes like '\\13' or escapes of ordinary letters (e.g. "\\n", "\\C") are rejected with this error, unlike some other DN parsers (notably Go's crypto/x509 behavior differs).

Source

Thrown at api/utils/pkixname/parser.go:547

				trailingSpaceBuf.WriteRune(r)
				state = tokenizeStateStringEnd
			case '=', '#': // Go does this.
				// NOT OK per RFC, should be escaped.
				fallthrough
			default:
				buf.WriteRune(r)
			}

		case tokenizeStateStringEscape:
			switch r {
			case ' ': // Go does this.
				// OK per RFC and allows the "\\ " trick.
				fallthrough
			case ',', '=', '+', '<', '>', '#', ';', '\\', '"':
				buf.WriteRune(r)
				escapeEnd()
			default:
				return nil, fmt.Errorf("unexpected escaped character %q: %s", r, errTrace(pos))
			}

		case tokenizeStateStringQuote:
			switch r {
			case '\\':
				escapeStart()
			case '"':
				emitBuffer(tokenString)
				state = tokenizeStateStringQuoteEnd
			default:
				buf.WriteRune(r)
			}

		case tokenizeStateStringQuoteEnd:
			switch r {
			case '+', ',', ';':
				transitionToNameComponent(r)
			default:

View on GitHub (pinned to 1283425b60)

Solutions

  1. Remove the unnecessary escape if the character needs none: "CN=A\\41" → "CN=A".
  2. Escape only the RFC specials or space: use '\\,' not '\\13' for a comma.
  3. Replace hex escapes with the literal character: "CN=\\6E" → "CN=n".
  4. Sanitize/unescape non-special backslash sequences before passing the DN to ParseDistinguishedName.

Example fix

// before
name, err := pkixname.ParseDistinguishedName("CN=Bob\\41")
// after
name, err := pkixname.ParseDistinguishedName("CN=BobA")
Defensive patterns

Strategy: validation

Validate before calling

var badEscapeRe = regexp.MustCompile(`\\[^ ,=+<>#;\\" ]`)
func hasInvalidEscape(dn string) bool { return badEscapeRe.MatchString(dn) }

Try / catch

name, err := pkixname.ParseDistinguishedName(dn)
if err != nil {
	if strings.Contains(err.Error(), "unexpected escaped character") {
		return nil, fmt.Errorf("DN %q uses unsupported escapes (only specials and space): %w", dn, err)
	}
	return nil, err
}

Prevention

When it happens

Trigger: Calling ParseDistinguishedName with a DN containing an escape of a character outside the allowed set, e.g. "CN=Bob\\, Jr." is fine but "CN=Bob\\n", "CN=A\\41", or "O=Corp\\t" fail.

Common situations: DNs escaped for a different parser (e.g. LDAP filter-style or Java LDAP escaping of non-specials), hex-escaped values copied from other tools, or accidentally doubled backslashes.

Related errors

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/ca5685ba0166d219. Report an issue: GitHub.