gastownhall/beads · error

failed to parse memory record: %w

Error message

failed to parse memory record: %w

What it means

A JSONL line whose `_type` is "memory" failed to unmarshal into the internal memoryRecord struct. The line is valid JSON (it passed the peek) but does not match the expected memory shape (Key/Value fields with correct types).

Source

Thrown at cmd/bd/import.go:275

		// Skip the optional beads-jsonl header record (§J1.3). A canonical
		// export may prepend a provenance line, e.g.
		// {"_schema":"beads-jsonl/1","_dolt_branch":"main","_sort":"stable-v1"}.
		// It carries no _type and no issue fields; without this guard it falls
		// through to the issue path, unmarshals into an empty Issue, and aborts
		// the whole import with "title is required". parseJSONLFile (the
		// bootstrap reader) has always skipped it; this loop — the one `bd
		// import` and `bd import -` run through — did not.
		if _, isHeader := peek["_schema"]; isHeader {
			continue
		}

		if rawType, ok := peek["_type"]; ok {
			var typeStr string
			if err := json.Unmarshal(rawType, &typeStr); err == nil && typeStr == "memory" {
				var mem memoryRecord
				if err := json.Unmarshal([]byte(line), &mem); err != nil {
					return nil, nil, fmt.Errorf("failed to parse memory record: %w", err)
				}
				if mem.Key != "" && mem.Value != "" {
					memories = append(memories, mem)
				}
				continue
			}
		}

		var issue types.Issue
		if err := json.Unmarshal([]byte(line), &issue); err != nil {
			return nil, nil, fmt.Errorf("failed to parse issue from JSONL: %w", err)
		}
		if issue.Status == "tombstone" {
			continue
		}
		applyImportWispPlane(peek, &issue)
		issue.SetDefaults()
		issues = append(issues, &issue)

View on GitHub (pinned to 71377f2769)

Solutions

1. Inspect the failing line and give it the expected shape: {"_type":"memory","key":"...","value":"..."}
2. Quote/unescape properly: value must be a JSON string, not a nested object or null
3. Re-export memories from the source repo with `bd export` rather than synthesizing them
4. Check source and target `bd --version` for schema drift between releases

Example fix

// before
{"_type":"memory","key":"team","value":{"name":"core"}}
// after
{"_type":"memory","key":"team","value":"core"}

jq -c 'select(._type=="memory") | has("key") and has("value") and (.value|type=="string")' file.jsonl

if ! bd import data.jsonl 2>err.log; then
  grep 'failed to parse memory record' err.log   # fix that record's key/value types
fi

When it happens

Trigger: `bd import` encounters a `"_type":"memory"` record whose JSON structure mismatches memoryRecord — e.g. `key`/`value` fields of wrong JSON types, null where a string is required, or a record assembled by hand or from another tool's schema.

Common situations: Hand-crafting memory records for `bd` config-style memories; importing JSONL produced by an older/newer beads version with a different memory schema; scripted line rewriting that broke field types.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• parsing JSON: %w
• failed to parse gh output: %w
• parse gh output: %w
• failed to parse JSONL line: %w
• failed to parse issue from JSONL: %w

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/8f2a22b83e6662a4. Report an issue: GitHub.