What causes "must be an RFC 6901 JSON Pointer" in larksuite/cli?

Prefix the pointer with '/', e.g. "/data/items"

must be an RFC 6901 JSON Pointer

Error message

must be an RFC 6901 JSON Pointer

What it means

Thrown by resolveShapePointer when a shape override pointer is not a valid RFC 6901 JSON Pointer — specifically it must start with '/' (and segments must use ~0/~1 escaping). Empty pointers are allowed and mean 'no override'.

Source

Thrown at shortcuts/common/typed_compile_contract.go:125

		index++
		switch segment[index] {
		case '0':
			builder.WriteByte('~')
		case '1':
			builder.WriteByte('/')
		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) {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Prefix the pointer with '/', e.g. "/data/items"
Escape literal '~' as '~0' and '/' as '~1' inside segments
Pass "" (empty) to skip the override

Example fix

// before
pointer := "data.items"
// after
pointer := "/data/items"

Defensive patterns

Strategy: validation

Validate before calling

func validPointer(p string) bool {
  return p == "" || strings.HasPrefix(p, "/")
}

Type guard

func isRFC6901Pointer(s string) bool {
  if s == "" { return true }
  if !strings.HasPrefix(s, "/") { return false }
  for _, seg := range strings.Split(strings.TrimPrefix(s, "/"), "/") {
    if !validSegment(seg) { return false }
  }
  return true
}

Try / catch

shape, err := common.ResolveShapePointer(base, ptr)
if err != nil {
  return fmt.Errorf("shape override pointer %q: %w", ptr, err)
}

Prevention

Convert dot-notation paths to slash notation with a leading '/'
Remember ~0 and ~1 escaping for literal '~' and '/'
Keep pointers as constants next to the shape they override

When it happens

Trigger: Passing pointer "data.items" or "items" (no leading slash) to the shape-override resolution path, e.g. in a data-shape override used by compileDataOverride.

Common situations: Writing a dot-notation path (data.items) instead of slash notation (/data/items); forgetting the leading slash for root-level fields; hand-rolling pointer strings in tests.

Related errors

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