larksuite/cli · error

invalid escape: ~ must be followed by 0 or 1

Error message

invalid escape: ~ must be followed by 0 or 1

What it means

decodeJSONPointerSegment enforces RFC 6901 escape sequences: a '~' inside a pointer segment must be followed by '0' (literal '~') or '1' (literal '/'). A segment ending with a bare '~' has no following character, so the segment is rejected.

Source

Thrown at internal/binding/json_pointer.go:67

		if !exists {
			return nil, fmt.Errorf("json pointer %q: key %q not found", pointer, key)
		}

		current = val
	}

	return current, nil
}

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 the literal tilde as '~0' (e.g. "/mykey~0" for key "mykey~")
2. Remove the trailing '~' if it was accidental
3. Expand '~' home-dir references to a full path before building the pointer

Example fix

// before
ReadJSONPointer(data, "/secret~")
// after
ReadJSONPointer(data, "/secret~0")

func sanitizeSegment(s string) string {
    return strings.ReplaceAll(strings.ReplaceAll(s, "~", "~0"), "/", "~1")
}

val, err := binding.ReadJSONPointer(data, ptr)
if err != nil && strings.Contains(err.Error(), "invalid escape") {
    // rebuild pointer with escapeSegment applied per key
}

When it happens

Trigger: Pointer segment ends with '~', e.g. "/mykey~" or "/a/b~" during ReadJSONPointer traversal.

Common situations: Keys whose literal names end with '~' that weren't escaped to '~0'; truncated pointers; tilde used as a shell home-dir abbreviation and passed through unescaped.

Related errors

• json pointer %q: segment %q: %w
• invalid escape: ~%c must be ~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/53cd226cbbccdea9. Report an issue: GitHub.