larksuite/cli · error
segment %q has invalid RFC 6901 escaping
Error message
segment %q has invalid RFC 6901 escaping
What it means
resolveShapePointer walks an RFC 6901 JSON Pointer through a compiled shape. Each '/'-separated segment must be validly escaped per RFC 6901 (~0 = '~', ~1 = '/'); if a segment decodes invalidly, the library rejects the pointer rather than guessing at the target field. This protects override paths from silently targeting the wrong field.
Source
Thrown at shortcuts/common/typed_compile_contract.go:131
default:
return "", false
}
}
return builder.String(), true
}
func resolveShapePointer(shape typedValueShape, pointer string) (typedValueShape, error) {
if pointer == "" {
return shape, nil
}
if !strings.HasPrefix(pointer, "/") {
return nil, fmt.Errorf("must be an RFC 6901 JSON Pointer")
}
current := shape
for _, encoded := range strings.Split(strings.TrimPrefix(pointer, "/"), "/") {
name, valid := decodeJSONPointerSegment(encoded)
if !valid {
return nil, fmt.Errorf("segment %q has invalid RFC 6901 escaping", encoded)
}
var err error
current, err = resolveShapeField(current, name)
if err != nil {
return nil, err
}
}
return current, nil
}
func resolveShapeField(shape typedValueShape, name string) (typedValueShape, error) {
switch value := shape.(type) {
case typedObjectShape:
for _, field := range value.Fields {
if field.Name == name {
return field.Shape, nil
}
}View on GitHub (pinned to 7fd6ef3c07)
Solutions
- Escape every literal '~' in a segment as '~0' and every '/' as '~1', e.g. "/a~1b/~0name" for fields 'a/b' and '~name'.
- Remove unnecessary '~' characters from the override Path if no escaping was intended.
- Verify the pointer targets an existing field via resolveShapeField by checking the struct shape first.
Example fix
// before
TypedDataDefinition{Overrides: []TypedDataOverride{{Path: "/na~me", Value: 1}}}
// after
TypedDataDefinition{Overrides: []TypedDataOverride{{Path: "/na~0me", Value: 1}}} Defensive patterns
Strategy: validation
Validate before calling
func validJSONPointer(p string) bool {
if p == "" || p[0] != '/' { return false }
for _, seg := range strings.Split(strings.TrimPrefix(p, "/"), "/") {
for i := 0; i < len(seg); i++ {
if seg[i] == '~' {
if i+1 >= len(seg) || (seg[i+1] != '0' && seg[i+1] != '1') { return false }
i++
}
}
}
return true
} Prevention
- Escape '~' as '~0' and '/' as '~1' whenever building pointer segments from arbitrary field names
- Keep a helper that constructs pointers from segments and does the escaping
- Test override paths against invalid-escape cases like "~2" and trailing "~"
When it happens
Trigger: Calling compileData (via a typed output definition with Output.Data.Overrides, or applyDataOverride) with an override Path containing a '~' not followed by '0' or '1', e.g. "/fields/~2/name" or a trailing lone '~'.
Common situations: Hand-writing JSON Pointer override paths and escaping '~' incorrectly; building paths programmatically with string concatenation without escaping '~' (e.g. field names containing '~'); copying pointers from non-RFC-6901 systems.
Related errors
- must be an RFC 6901 JSON Pointer
- field %q does not exist
- Output.Data.Overrides[%d].Path %q must be an RFC 6901 JSON P
- json pointer must start with '/' or be empty, got %q
- segment %q traverses non-object shape
AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04).
Data as JSON: /api/errors/3b7f7415303f4799.
Report an issue: GitHub.