Skip to main content

PostgreSQL import problem

Diagnose PostgreSQL COPY CSV Import Errors

Prepare a CSV for PostgreSQL COPY by checking headers, delimiters, null rules, encoding and rejected field values.

Use the matching tool

CSV Diagnostic

Open CSV Diagnostic

What the error actually means

PostgreSQL COPY has explicit CSV options for the delimiter, header, quote, escape, null representation and encoding. A structurally valid CSV can still fail when a value cannot be converted to the destination column type. PostgreSQL CSV also distinguishes an unquoted empty field from a quoted empty string under its default null rules.

Likely causes

  • The COPY delimiter or encoding does not match the file.
  • The header order differs from the target column list.
  • An empty string is being interpreted differently from NULL.
  • A date, number or boolean value violates the destination type.

Explicit COPY contract

Problem

COPY target FROM file with implicit defaults

Correct pattern

COPY target(cols) FROM file WITH (FORMAT csv, HEADER true, ENCODING 'UTF8')

A safe repair workflow

  1. 1Run a CSV structural diagnostic before touching the database.
  2. 2Define the target column list and COPY options explicitly.
  3. 3Load into a staging table when values need normalization.
  4. 4Reconcile inserted and rejected rows before moving data into production tables.

How to verify the result

A file that downloads successfully is not automatically a correct file. Check the result at both the structural and business-data levels:

  • Header names and order match the specified columns.
  • Null and empty-string cases behave as intended.
  • Date and numeric ranges are plausible after import.
  • Source, inserted and rejected counts reconcile.

Read the deeper guides

Import CSV to MySQL/PostgreSQL (Step-by-Step Guide)Learn how to import CSV files into MySQL and PostgreSQL databases. Command-line and GUI methods with error handling and best practices.Diagnose a Broken CSV Before You Try to Repair ItA methodical way to identify delimiter, encoding, header, quoting, row-shape, and type problems before a CSV reaches Excel, a CRM, or a database.

Official references

Platform requirements and technical standards can change. These are the primary references used for this page.