larksuite/cli · error

json pointer %q: segment %q: %w

Error message

json pointer %q: segment %q: %w

What it means

While walking the pointer, each segment is unescaped per RFC 6901 (~1 → '/', ~0 → '~') by decodeJSONPointerSegment. If a segment contains a malformed '~' escape, the traversal aborts and wraps that segment error with the full pointer and the offending segment.

Source

Thrown at internal/binding/json_pointer.go:38

// SecretRef file provider uses object-only paths in practice.
func ReadJSONPointer(data interface{}, pointer string) (interface{}, error) {
	if pointer == "" {
		return data, nil
	}

	if !strings.HasPrefix(pointer, "/") {
		return nil, fmt.Errorf("json pointer must start with '/' or be empty, got %q", pointer)
	}

	// Split after the leading "/" and decode each segment.
	segments := strings.Split(pointer[1:], "/")
	current := data

	for i, raw := range segments {
		// RFC 6901 unescaping: ~1 → /, ~0 → ~ (order matters).
		key, err := decodeJSONPointerSegment(raw)
		if err != nil {
			return nil, fmt.Errorf("json pointer %q: segment %q: %w", pointer, raw, err)
		}

		m, ok := current.(map[string]interface{})
		if !ok {
			traversed := "/" + strings.Join(segments[:i], "/")
			return nil, fmt.Errorf("json pointer %q: value at %q is %T, not an object",
				pointer, traversed, current)
		}

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

		current = val
	}

	return current, nil

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Replace invalid escapes: use ~0 for a literal '~' and ~1 for a literal '/'
2. Remove stray '~' characters or escape them (~0)
3. Check the segment at the index reported in the error string

Example fix

// before
ReadJSONPointer(data, "/path~2to/key")
// after
ReadJSONPointer(data, "/path~0to/key")

if strings.Contains(ptr, "~") && !regexp.MustCompile(`~[01]`).MatchString(ptr) {
    return errors.New("pointer contains invalid ~ escape")
}

val, err := binding.ReadJSONPointer(data, ptr)
if err != nil && strings.Contains(err.Error(), "invalid escape") {
    ptr = strings.ReplaceAll(ptr, "~", "~0") // re-escape and retry
    val, err = binding.ReadJSONPointer(data, ptr)
}

When it happens

Trigger: Pointer contains '~' not followed by 0 or 1 (or a trailing '~'), e.g. "/data/~2/key" or "/data/~".

Common situations: Keys that literally contain '~' were not escaped as '~0'; hand-written pointers guessing at the escape syntax; templated paths where a '~' home-dir token leaked into the pointer.

Related errors

• invalid escape: ~ must be followed by 0 or 1
• 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/6c398def14e91207. Report an issue: GitHub.