json-archive/docs/diagnostics/json-pointer.md

<!-- Generated by: cargo run --bin pointer_errors_demo > docs/diagnostics/json-pointer.md -->

# JSON Pointer Diagnostics

These are the error messages you'll see when a [JSON Pointer (RFC 6901)](https://datatracker.ietf.org/doc/html/rfc6901)
operation fails.

## Why These Errors Are Limited

The JSON object that failed to index probably doesn't exist anywhere as a file. It's
built by replaying delta events from the archive. The filename and line numbers in
these errors point to the source of the JSON pointer paths—the add/change/remove
events in the archive—not to the object itself.

A proper solution would dump the reconstructed JSON object to a file so you could
inspect it with `jq` or a text editor. That engineering work didn't happen.

Instead, you get:

- The pointer path that failed, with the failing segment underlined
- The actual value at the parent path (truncated)
- Some strings you can grep for in the archive

This is better than nothing, but it's still awkward. You can see *what* failed but
not easily inspect the full object we tried to index into. If you're lucky, the
truncated value shown is enough. If you're developing on this project, at least
you know what the errors look like.

## Contributing

If an error message is confusing or unhelpful for your case, please open an issue
or submit a pull request.

## Key Not Found

Key doesn't exist in the object. Shows available keys and suggests typos.

```
error E051: Path not found

I was traversing the JSON path '/user/emial' and got stuck.

I couldn't find the key 'emial'.

  /user/emial
        ^^^^^

Value at '/user':
│ "age": ...
│ "email": ...
│ "name": ...

Available keys: age, email, name
Did you mean 'email'?
```

## Type Mismatch

Tried to index into a value that doesn't support it (e.g., `/domain` on a string,
`/0` on a number). Shows the actual type.

```
error E060: Type mismatch

I was traversing the JSON path '/users/0/email/domain' and got stuck.

I can't index into string with 'domain'.

  /users/0/email/domain
                 ^^^^^^

Value at '/users/0/email':
│ "alice@example.com"

Object keys like '/domain' only work on objects, not string.
```

## Array Index Out of Bounds

Index past the end of the array. Shows the array length.

```
error E051: Path not found

I was traversing the JSON path '/items/5' and got stuck.

I couldn't find index 5 (array length is 3).

  /items/5
         ^

Value at '/items':
│ 0: "apple"
│ 1: "banana"
│ 2: "cherry"

Valid indices are 0-2.
```

## Array Index

If you think you have an object but you're actually indexing into an array, you'll see this error.

```
error E052: Invalid array index

I was traversing the JSON path '/items/foo' and got stuck.

I couldn't parse 'foo' as an array index.

  /items/foo
         ^^^

Value at '/items':
│ 0: "apple"
│ 1: "banana"
│ 2: "cherry"

Array indices must be non-negative integers. Got 'foo'.
```

## Deep Path Failures

For long paths, the underline shows which segment failed. The full path remains
visible so you can see what you were trying to reach.

```
error E051: Path not found

I was traversing the JSON path '/data/users/0/profile/settings/theme' and got stuck.

I couldn't find the key 'settings'.

  /data/users/0/profile/settings/theme
                        ^^^^^^^^      

Value at '/data/users/0/profile':
│ "name": ...

Available keys: name
```