gastownhall/beads · error

failed to parse issue from JSONL: %w

Error message

failed to parse issue from JSONL: %w

What it means

A JSONL line that is neither a header nor a memory record is unmarshaled into types.Issue, and that unmarshal failed. Since the line is valid JSON, the problem is the payload not conforming to the Issue schema (wrong field types, unknown enum values, etc.).

Source

Thrown at cmd/bd/import.go:286

		}

		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)
	}
	if err := scanner.Err(); err != nil {
		return nil, nil, fmt.Errorf("failed to scan JSONL: %w", err)
	}
	return issues, memories, nil
}

// runImportRecordsClassic is the classic (embedded/direct store) import
// pipeline over the parsed records: dedup, dry-run classification, memory
// writes, the batch issue import, the final commit and the issue_prefix
// reconciliation.

View on GitHub (pinned to 71377f2769)

Solutions

1. Fix the reported field's JSON type to match the Issue schema (e.g. numeric priority, array labels)
2. Re-export from the source repo with `bd export -o file.jsonl` to get canonical records
3. Remove unrelated JSON documents from the stream
4. Check beads release notes for Issue schema changes if the export predates your binary

Example fix

// before
{"id":"bd-1","title":"Bug","priority":"P1"}
// after
{"id":"bd-1","title":"Bug","priority":1,"status":"open"}

jq -c 'select(._type==null or ._type!="memory") | (.priority|type=="number") and (.labels|type=="array")' file.jsonl

if ! bd import data.jsonl 2>err.log; then
  grep 'failed to parse issue from JSONL' err.log   # fix field types on that line
fi

When it happens

Trigger: `bd import` reads a record whose fields collide with types.Issue — e.g. `priority` as a string "P1" instead of a number, `status` not a known string, `labels` as an object instead of an array, or an entirely different JSON document passed by mistake.

Common situations: Importing JSONL exported by another tool or an older beads version; hand-written issues with wrong field types; accidentally passing a JSON config file to `bd import`.

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

• failed to parse issues response: %w
• failed to parse team states response: %w
• unable to parse plugin file v2: %w
• parsing JSON: %w
• failed to parse gh output: %w

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