## TL;DR
Validate the export's shape before parsing fields: Neptune metadata exports nest attributes under typed structures, and a decode error usually means the file is truncated, is a different export type than expected, or contains a wrapper the parser did not unwrap. Load the JSON defensively, print its top-level keys, and map fields from the observed structure instead of an assumed one.

```text
agent couldn't parse Neptune run metadata JSON and failed with a JSON decode error
```

## Use this when
- The run or call fails with this symptom: agent could not parse Neptune run metadata JSON and failed with a JSON decode error.
- You are working on an agent consuming Neptune run metadata exported as JSON and the failure repeats on the same run or configuration.
- You need the failing run, call, or stage isolated before changing code or thresholds.

## Not for this skill when
- A file that is actually JSON lines rather than a single JSON document, where the fix is line-wise parsing.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Check the file's size and its first and last characters to see whether it is a complete single document. Verify: file completeness is established
2. Load it with a standard JSON parser and capture the error position if it still fails. Verify: the exact failure point is known or the document loads
3. Print the top-level structure and locate where run attributes actually live, including typed value wrappers. Verify: the real field paths are mapped
4. Rewrite the extraction against the observed structure and validate a few runs' values against the Neptune UI. Verify: extracted values match the source

## Variant phrasings
### agent parse neptune run metadata json decode error
The verbatim phrasing.
### neptune metadata export json structure agent failed
The structure phrasing.
### agent json decode error experiment metadata fix inspect
The inspection phrasing.

Compatibility: Agent parsers reading Neptune run metadata exports as JSON

## Why it happens
Decode errors conflate several causes, truncation, wrong format variant, and wrapper structures, into one exception. The structure has to be observed before it can be parsed, which is why inspecting the document's shape precedes any field logic.

## Edge cases / pitfalls
- Streaming exports can be JSON lines; detect by attempting a whole-file load first, then falling back deliberately.
- Typed wrappers around numbers are the field-level trap after the document parses; unwrap them in one helper.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst__XROJcemzeAyZr7Sg23JwQ