Skip to main content

Import Validation and Offline Imports

What Importing Contacts does with a record it can't read, and how the whole workflow behaves when you are offline, on a new device, or importing a very large file.

Validation and warnings​

The importer is conservative — bad records are dropped or normalized at parse time so they don't pollute your log. Failures appear as unreadable records with a reason. For a CSV you get the physical line number — Row 12 is line 12 of the file, the row your spreadsheet shows — which stays correct even when the header is not on the first line. ADIF records are not line-bound, so those are numbered one-based as Record 1, Record 2, and so on.

What gets dropped or normalized:

  • Missing required fields — every record needs CALL, QSO_DATE, and TIME_ON.
  • Invalid date — the QSO_DATE must be a real YYYYMMDD between 1900-01-01 and one year from today. Feb 30, 99999999, year 1776, etc. are marked unreadable before routing.
  • Invalid time — TIME_ON / TIME_OFF must have hours < 24, minutes < 60, seconds < 60. A typo like 250000 is marked unreadable instead of becoming "25:00".
  • Garbled callsign — the instant structural check requires 3–15 characters, only letters, digits, and /, at least one letter and one digit, no empty or repeated-slash segments, no more than four slash-delimited segments, and at least one segment that mixes letters and digits (the base call). This is a fast shape check, not a live callsign-directory lookup.
  • Oversized or malformed field — an ADIF or CSV field inside a QSO over 5,000 characters makes the parser skip that whole record, matching the cloud's scalar-string boundary before the contact reaches the save queue. Leading PoLo APP_HAM2K_* operation events are ignored as non-QSO metadata before this limit, so even a large event cannot contaminate or swallow the contact after it. For other ADIF fields, parsing resumes at the next <EOR> because a bogus length prefix makes the current record's boundaries untrustworthy. For CSV, a closed oversized field is skipped without losing later rows; an unclosed quoted field is reported as unreadable instead of being silently folded into a contact. Cloud acceptance separately caps the full normalized command at 64 KiB and preserved unknown ADIF data at 256 fields with 64-character names. Parser acceptance still does not promise that an arbitrarily large record can be stored.
  • Frequency out of range — anything ≤ 0 or ≥ 300,000 MHz is normalized to 0 (the BAND field, if present, is still used).

Offline imports​

ADIF and CSV imports work without an internet connection on a device that has already loaded your logbook at least once — skipping duplicates means comparing your file against that local copy, so Hamtrax needs a complete one before it can plan. On a device that has never finished loading it, an offline import stops before Review and asks you to connect and Retry; a successful retry keeps the parsed input and resumes at the Select source summary. If the same proof is lost later at the Finalize step, Retry returns to Review with the refreshed plan. See ② Duplicates. QRZ import requires a connection while the remote contacts are fetched. Once a plan is confirmed, contacts are saved to your local database and accepted folder assignments sync to the cloud when you reconnect.

Offline there is nothing for your logbook to answer yet, so nothing can be refused and nothing on the finish screen asks anything of you: every contact counts as imported, because it is saved and waiting to travel the moment you reconnect. A very large import that is still travelling when the summary appears reads the same way. If your logbook does turn one of those contacts away once it arrives, that contact appears under Needs Filing rather than on a screen you left long ago.

If the cloud permanently rejects an imported contact after reconnecting, Hamtrax shows a warning notification (once for the batch, not once per row) and keeps the original command plus saved reason category on that browser or device under Logbook → Needs Filing. The shared review row turns that category into plain language and never displays an internal contact id or raw server message. Only a new contact classified as a folder-hygiene rejection offers Choose folder and an explicit destination in the Logbook; any other permanent imported-create rejection remains review-only. A filing attempt leaves the original marked Saving corrected contact until the cloud accepts the replacement, and the item is not cloud-backed or available on another device before then.

An oversized command is never silently counted as cloud-saved: it remains accounted for on the originating device with its rejection, but it is not available on another device unless a valid replacement is accepted.

Large files (10,000+ QSOs) parse in a few seconds. Destination cards render contacts in user-requested chunks of 200; the full valid set is still queued. Filing sends both folders and contacts to your logbook in groups rather than one at a time, which makes a large import file many times faster, and it hands the logbook back between groups so a contact you add by hand never waits for the import to end. A file spanning years of activating and hunting can need well over a hundred folders; those are created on your device in one pass and then sent up together, so Creating folders passes in seconds instead of a round trip apiece. A contact travels as soon as your logbook has accepted the folder it belongs in, so an import spread across dozens of folders is not held back by the last of them. The Logbook's folder tree takes those new folders in one pass as well and then holds still while contacts file into them, instead of redrawing itself over and over behind the finish screen. Because browser imports, CLI logging, and automatic imports share the account's cloud work budget, an unusually large import may pause at a UTC reset and continue afterward. The exact idempotent rows stay on the originating device and resume without being duplicated.

Getting-started checklist

A user-initiated import completes Import contacts when at least one new contact is added. A duplicate-only import does not complete it, and the automatic public POTA starter import that may run after signup does not count as this hands-on setup step.