larksuite/cli · error

invalid escape: ~%c must be ~0 or ~1

Error message

invalid escape: ~%c must be ~0 or ~1

What it means

Same escape-validation rule, but for a '~' followed by a character other than '0' or '1'. RFC 6901 defines only ~0 and ~1; any other combination (e.g. ~2, ~x) is invalid and rejected with the offending pair shown in the message.

Source

Thrown at internal/binding/json_pointer.go:75

}

func decodeJSONPointerSegment(raw string) (string, error) {
	var out strings.Builder
	for i := 0; i < len(raw); i++ {
		if raw[i] != '~' {
			out.WriteByte(raw[i])
			continue
		}
		if i+1 >= len(raw) {
			return "", fmt.Errorf("invalid escape: ~ must be followed by 0 or 1")
		}
		switch raw[i+1] {
		case '0':
			out.WriteByte('~')
		case '1':
			out.WriteByte('/')
		default:
			return "", fmt.Errorf("invalid escape: ~%c must be ~0 or ~1", raw[i+1])
		}
		i++
	}
	return out.String(), nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Escape each literal '~' as '~0': key "a~2b" → segment "a~02b"
2. Only ~0 and ~1 are valid — rewrite any other '~X' sequence
3. Audit the source string for stray '~' characters

Example fix

// before
ReadJSONPointer(data, "/key~2name")
// after
ReadJSONPointer(data, "/key~02name")

var validEscape = regexp.MustCompile(`(^|[^~])~[01]`)
func escapesOK(ptr string) bool { return validEscape.MatchString(ptr) || !strings.Contains(ptr, "~") }

When it happens

Trigger: Pointer segment contains "~2", "~x", "~~" (second ~ treated as the follower), etc., passed to ReadJSONPointer.

Common situations: Keys literally containing '~~' or '~<digit>' sequences written unescaped; copying pointer syntax from other standards that allow more escapes; regex or glob characters bleeding into the pointer string.

Related errors

• json pointer %q: segment %q: %w
• invalid escape: ~ must be followed by 0 or 1
• json pointer must start with '/' or be empty, got %q
• json pointer %q: value at %q is %T, not an object
• json pointer %q: key %q not found

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/810e6ee05e603fdb. Report an issue: GitHub.