GEDCOM error messages, decoded

An upload failed and the site gave you a sentence. Invalid GEDCOM file. Unable to import GEDCOM. Error 20. The sentence names no line, no record and no byte. Search it and you get forum threads where five people guess.

An error message can narrow your checks, but different programs reuse broad phrases for different failures. You cannot infer a specific bad byte or repair from a generic message alone.

What causes it, message by message

Use the first column to choose an initial check. The codes below are findings to look for in this site's Inspector or Validator, not translations of another program's error codes.

Partial imports and wrong characters can originate in the export, transfer or destination. Compare the original before assigning a cause. Custom-tag compatibility and encoding repair cover those checks. A missing 0 TRLR merits review but does not prove that record data is missing.

Which tool reads which message

Diagram source

flowchart TD
  M["You have a refusal message"] --> I["File Inspector: drop the file"]
  I --> P{"What does Problems list?"}
  P -- "missing-head, level-jump, malformed-line, duplicate-xref, missing-trlr" --> R["Corrupted File Recovery"]
  P -- "invalid-utf8, charset-mismatch, undefined-ansel-byte" --> E["Encoding Repair"]
  P -- "nothing, and the counts look right" --> V["GEDCOM Validator and destination requirements"]
  R --> RV["Validate the recovered file"]
  E --> RV
  V --> D["Review findings and test supported output in a separate tree"]

The fix

1. Open File Inspector and drop the file on the drop target. Parsing runs in your browser; nothing is uploaded.
2. Read Header. It states the GEDCOM version, the producer, the declared charset, what it was decoded as and the line endings. On broken-structure-synthetic.ged the version reads 5.5.1, the producer reads GEDTK-TEST (GED Toolkit synthetic fixture) and line endings read LF.
3. Read Records by type. On the same file it lists INDI 2, FAM 1, HEAD 1. A lower count than expected calls for checking export scope, malformed records or truncation. Inspector continues through malformed input; the count does not prove it stopped early.
4. Read the Problems table. Its four columns are Line, Severity, Code and Message. On this file the section title reads Problems: 1 errors, 1 warnings, 0 info and it holds two rows: line 15, error, level-jump, Level jumps from 2 to 9; and not recorded, warning, missing-trlr, File has no 0 TRLR record.
5. Match local findings to the third column above. Inspector displays the first 200 problem rows while its totals cover all findings. A local problem is evidence to investigate, not proof of what caused the other program's message.
6. For any code in the first branch of the diagram, open Corrupted File Recovery and drop the same file.
7. Read Byte accounting first. On this file it reads 542 kept + 0 dropped = 542; input 542. Every input byte is accounted for. The line below adds that 70 of the kept bytes sit in rewritten lines and the output is 541 bytes. Kept bytes can belong to rewritten facts; this arithmetic does not prove unchanged meaning.
8. Read Records. The columns are Type, Input, Recovered. On this file TRLR goes from 0 to 1, because the trailer was synthesised, and INDI holds at 2.
9. Read Changes and findings: 3. Two are tagged rewritten and one synthesized: Line 15: level 9 after a level 2 line; re-levelled to 3 under PLAC at 60% confidence, 8 line terminators rewritten to LF at 90%, and 0 TRLR appended at 95%. These results use the default, ticked Rewrite minority line endings to the dominant one setting. Review the inferred nesting; confidence is not proof of the intended structure.
10. Keep the original, then click Download broken-structure-synthetic.recovered.ged under Output if you accept the changes. Recovery has no per-change accept/reject control. It previews the first 300 findings and loss ranges; use Download ledger (JSON) to inspect the operations. Review any warning that output characters became ? before using the file.
11. Open GEDCOM Validator and drop the recovered file. Read the three severity counts across the top: errors, warnings, infos.

What to check when it worked

• File Inspector on the recovered file lists no row of severity error under Problems.
• The Records table in Corrupted File Recovery shows the same INDI and FAM counts in the Input and Recovered columns. On broken-structure-synthetic.ged that is 2 and 1.
• Byte accounting balances, and you accept the rewritten lines and any dropped ranges.
• Review GEDCOM Validator errors, warnings and infos. Its severity labels do not predict a destination's import behavior.
• Test in a separate destination tree and compare counts and sample records. A changed error message does not establish how many original faults existed; investigate the new message before making another repair.

What to do when it did not

The message stayed the same and the Inspector found nothing. Check GEDCOM Validator, including referential, and the destination's version and file restrictions. How to find every broken pointer in a GEDCOM covers unresolved references that Inspector alone does not rule out.

The message changed to one about data. Compare the new message with remaining findings and missing output fields. Dialect Report supplies dated compatibility guidance, not a live test of that destination.

Records are missing from the Recovered column. Compare the recovery's dropped ranges and rewritten structure against the original. A lower recovered count can reflect changes made during this recovery. If the input itself lacks records, ask the sender for a fresh export; recovery cannot reconstruct absent bytes.

The recovery changed something you disagree with. Keep the original. Download ledger (JSON) lists operations, but the page offers no selective undo. Correct the source or obtain another export before accepting the recovered file.

Related

• Pillar: how to fix a GEDCOM file that will not open
• Sibling: how to fix garbled characters and accents in a GEDCOM
• What is ANSEL, and why your names look wrong
• How to check a GEDCOM before you import it anywhere