larksuite/cli · error

json pointer %q: key %q not found

Error message

json pointer %q: key %q not found

What it means

When a pointer segment names a key that is absent from the current object, traversal fails with this error. It reports the full pointer and the decoded key that was not found, making it clear which level of the path diverged from the document.

Source

Thrown at internal/binding/json_pointer.go:50

	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
}

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")
		}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Print/inspect the JSON and use an existing key at that level
2. Fix the key spelling/case in the pointer
3. Handle the missing key: check presence first or fall back to a default
4. Verify the document version matches the expected schema

Example fix

// before
ReadJSONPointer(data, "/accounts/oauth/id")
// after
ReadJSONPointer(data, "/accounts/app/id")

obj, err := ReadJSONPointer(data, "/accounts/app")
if err == nil {
    m := obj.(map[string]interface{})
    if _, ok := m["secret"]; !ok { /* use default */ }
}

func keyExists(m map[string]interface{}, key string) bool {
    _, ok := m[key]
    return ok
}

val, err := binding.ReadJSONPointer(data, ptr)
if err != nil && strings.Contains(err.Error(), "not found") {
    val = defaultValue // degrade gracefully for optional fields
}

When it happens

Trigger: ReadJSONPointer with a pointer whose key does not exist in the map at that level, e.g. "/accounts/oauth/id" when only "accounts.app" exists.

Common situations: Typo in a key; config schema changed between bridge versions (e.g. secret moved from accounts.app to a new block); case mismatch ("App" vs "app"); querying an optional field that was omitted.

Related errors

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

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