Solve a problem

“The input file does not match the input schema”

A column your config’s input.fields declares is missing from the file. The file is refused entirely and nothing is loaded — which also means a later export cannot write the wrong file’s rows under this file’s name.

Check the header row against your config. Names must match exactly (they are trimmed of surrounding whitespace, but not otherwise normalised — Model Score is not model_score).

Extra columns are only a warning; they are ignored.

A value shows as empty with a note

The cell could not be read as the type the config declares — text where a number was expected, an unparseable date, an enum value that is not one of the permitted choices.

You cannot fix this from inside MLabel, and you are not expected to. Label what you can. The original value is preserved in *-remaining if the record ends up there. If it affects many rows, the config’s declared type is probably wrong for the data — tell whoever wrote it.

The config won’t load

Errors include locations where available. Validation runs in stages; fix the current errors and try again to reveal any further problems. If you are a labeler, send the message to the administrator rather than changing the project definition yourself. Common causes:

Message contains	Cause
Unrecognized key	A typo. Every object is strict; unknown keys are errors.
no version / Unsupported config version	The config format is missing or incompatible.
does not match input field	A copy field’s type differs from its source column.
cannot be filled by a user	An object or map output field with no fill.
is reserved	A shortcut the app or OS already owns.

Administrators can find fixes in Configuration errors.

“These files already exist”

You have exported once already. MLabel will not overwrite a previous export — archive the existing *-output and *-remaining files, then press Save again. See Exporting.

My labels are gone

Check, in order:

1. Did you export? A successful export clears the saved session by design. Your work is in *-output; *-remaining contains only the unfinished source records, not partial answers.
2. Is it the same pair of files? Sessions are keyed to config and input path. A renamed or moved file is a different session.
3. Did you decline the resume prompt? Declining discards the saved session.
4. Is the saved-session format compatible? Incompatible session formats are discarded. This does not mean every application update discards your session.

The resume prompt says the file changed

The source file’s contents differ from when you last saved. Labels are stored by row position, so restoring onto a file whose rows were added, removed or reordered puts your labels on the wrong records. Keep the original files and ask your preparer how to recover the assignment before discarding saved answers.

Re-downloading a byte-identical file does not trigger this — only content is compared, never the modification time.

Updates never install

• macOS: the app is running from outside /Applications. See Install on macOS.
• Windows: you have the portable build, which cannot self-install. See Install on Windows.
• Either: your personal update preference may be off, or your config sets "network": { "updateChecks": false }, which disables all network activity.

A keyboard shortcut does nothing

Bare letter chords are suppressed while you are typing in a text box, textarea or dropdown search — otherwise that letter could never be typed. Ctrl, Cmd, and Alt combinations can remain active while typing; bare and Shift-only shortcuts pause. An open dialog takes the keyboard entirely. See Keyboard shortcuts.

Prepare refuses to join

Headers must match exactly, in order, across every file. The likeliest cause is mixing kinds — an *-output file among *-remaining ones — since those follow different schemas. Check the per-file list; each row shows what failed.