What Should a Data Import Command Print on Failure?
From the earlier reference collection. Read the current software blog.
Report the affected input and the actionable cause, then exit unsuccessfully so scripts do not mistake the import for a success.
Name the input and operation
A useful failure message answers two basic questions: which input failed, and what was the program doing when it failed? Could not import stops.txt: required column stop_id is missing gives an operator a clear starting point. Import failed does not identify the file, while a raw stack trace may bury the part that explains the problem.
Include a filename, source identifier, or other safe reference. If the path contains private information, report a suitably redacted path or stable source key. Avoid printing the entire input row when it could contain personal or confidential data.
Explain cause without guessing
State the observable cause in plain language: the archive could not be opened, the file ended unexpectedly, a required header was absent, or a connection attempt timed out. If the program cannot determine why, say what operation failed rather than inventing a diagnosis. Preserve a lower-level exception in a debug log when appropriate, but make the default message concise enough to act on.
For example, feed.zip: not a readable ZIP archive points to a format or download issue. If the file is a ZIP but stops.txt is absent, report that specific missing member. Those cases call for different fixes, and a precise message prevents needless retries or changes to unrelated parser code.
Use a nonzero exit status
A printed error alone does not tell a shell script that the command failed. Return a nonzero status for an unsuccessful import so automation can stop, alert, or preserve the previous dataset. Reserve zero for a completed operation under the command’s stated success criteria. If the command supports partial imports, define whether partial completion counts as failure and make that behavior consistent.
Send diagnostics to standard error, leaving standard output available for machine-readable results. This makes the program easier to compose with other commands and avoids an error sentence being mistaken for a data row.
Give the next step when known
When the remedy is clear, add one short instruction: Check that the archive is complete and retry or Update the mapping for column stop_id. Avoid generic advice such as try again if repetition cannot fix a malformed schema. Include a request or job ID when it helps an operator find detailed logs.
A well-designed failure report is a compact handoff from program to person or supervisor. It identifies the affected input, describes the evidence, signals failure to automation, and offers a safe next action when the program can justify one.