> ## Documentation Index
> Fetch the complete documentation index at: https://help.polygon-one.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Import errors (PPWR)
> Every PPWR import message verbatim — cause and resolution
## How to read the import result
A PPWR import almost never fails as a whole. After the import, the **Import Results** dialog shows three numbers (imported, updated, skipped) and below them a table of the errors with the columns **Identifier**, **Type** and **Error**. Valid rows are imported even when other rows fail.
The error table has **no** row-number column. **Identifier** holds the row's key (code, reference, or the pair of both); only when that is missing does the row number take its place. So find the affected row in your file by its identifier.
File errors are the exception: if the file cannot be read at all, nothing is imported (see [Errors affecting the whole file](#errors-affecting-the-whole-file)).
Search for the message you are seeing with the search at the top (`Ctrl`/`Cmd` + `K`) — every message is on this page verbatim.
## Required fields missing
### Code is required
> Code is required
**When does this happen?** In the **components import** the **Code** column is empty (or holds only spaces). The same error occurs on the packaging bill of materials via the API when the `componentCode` field is missing or empty.
**How to fix it:** Enter a code in every row. The code is — in the components import together with the **Supplier** column — the component's matching key; without it the import cannot decide whether to create or update a component. If your file carries the value in a differently named column, map that column once under **Settings → CSV Imports**.
### Name is required
> Name is required
**When does this happen?** The **Name** column is empty — in the **units import** or in the **components import**.
**How to fix it:** Add the name. It is the label under which the unit or component appears in the lists, and it is required in both imports.
### Reference is required
> Reference is required
**When does this happen?** The reference of an **existing** packaging unit that the row should refer to is missing — the `specInternalRef` field on both the packaging bill of materials and the article mapping via the API.
**How to fix it:** Add the packaging unit's internal reference. It is the unit's matching key — unlike the component code, the supplier plays no part here. You find the references in the **Packaging units** list or its export.
**In the units import this error no longer exists.** There the **Reference** column is optional: left blank, the import creates a **new** unit and assigns a reference automatically (`PU-1`, `PU-2`, …). That also means re-importing the same reference-less rows produces **duplicates** — details under [Leaving the reference blank](/en/ppwr/stammdaten/import#leaving-the-reference-blank).
### Description and intended use is required
> Description and intended use is required
**When does this happen?** In the **units import** the **Description & Intended Use** column is empty.
**How to fix it:** Describe briefly what the packaging is and what it is used for. The field is required because the PPWR Declaration of Conformity has to name the intended use — so the import cannot leave it blank. In older files the column is still called **Notes**; that header is still accepted.
### At least one material is required
> At least one material is required
**When does this happen?** In the **components import** the **Materials** column is **empty** — blank, only spaces, or only separators (`;`, `,`).
**How to fix it:** Enter at least one material. Accepted are `plastic`, `paper_board`, `glass`, `metal`, `wood`, `composite` and `other`, as well as their displayed labels. Separate several materials with `;` or `,`.
If the column holds a value the import does **not** know (e.g. `Plstic`), you do not get this message but **"Invalid value. Accepted values: …"** — see [below](#invalid-value-accepted-values).
### Article number is required
> Article number is required
**When does this happen?** On the article mapping via the API the `articleNumber` field is missing or empty.
**How to fix it:** Enter the **internal article number** of the article the unit should be linked to. The article must already exist — this interface creates no articles. In a file the same link is created through the **Article Numbers** column of the units import; the two doors behave differently on purpose, though: **the column skips an unknown number without an error row, the API fails the row.**
## Invalid values
### Invalid value. Accepted values: …
> Invalid value. Accepted values: `{values}`. Use a value from the import template or configure a value mapping under Settings → CSV Imports.
**When does this happen?** A **coded column** holds a value the import does not know. Affected are **Packaging Type**, **Role**, **Recyclability Grade**, **Materials**, **Polymer**, **Recycled Source**, **Recycled Method**, **Heavy Metals Basis** and **PFAS Basis**. The message always lists the accepted values.
Two spellings are accepted per value: the **code** (`plastic`) and the **label** in your interface language (`Plastic`). Case and surrounding whitespace do not matter; the label has to match exactly, though — `Plstic` or `Paper` instead of `Paper / board` fail.
**How to fix it:** Two routes:
1. **Correct the file** — replace the value with one of those named in the message.
2. **Add a value mapping** (file import only) — when your file permanently uses its own spellings (e.g. `PE film` or an ERP abbreviation): open **Settings → CSV Imports**, pick the **Packaging units** or **Components** tab, expand **Custom value mappings** under the column and enter your spelling in the field of the matching value. The mapping applies to every file from the next import on. Details under [Custom value mappings](/en/ppwr/stammdaten/import#custom-value-mappings).
**This does not apply over the API.** Neither your value mappings nor the displayed labels are evaluated there — `Kunststoff` is rejected. Over the API, always send the **code** (`plastic`).
For the shipped labels with a parenthetical, both work in the file import: with and without the part in brackets (`Post-consumer` as well as `Post-consumer (PCR)`).
A value mapping helps **only** with this message. For record-matching errors — **Ambiguous component code**, **No component with this code**, **No packaging unit with this reference** — there is no value mapping; there the code or reference counts character for character.
### Invalid yes/no value
> Invalid yes/no value. Use yes/no, true/false, 1/0, or x.
**When does this happen?** A yes/no column holds something other than one of the known spellings — affected are **Own Brand**, **Modifies Conformity**, **Reusable**, **Contact-sensitive**, **Food-contact** and **PFAS Compliant**.
**How to fix it:** Use `yes`/`no`, `ja`/`nein`, `true`/`false`, `1`/`0`, `y`/`n` or `x` (for "yes"). An **empty** cell is not an error: it means **no** — for **PFAS Compliant**, however, **unknown**.
### Must be a non-negative number
> Must be a non-negative number
**When does this happen?** A numeric field holds a non-number or a negative number. Affected are **Width (mm)**, **Height (mm)**, **Depth (mm)**, **Mass (g)**, **Heavy Metals (mg/kg)**, **PFAS Sum (ppb)** and **Total Fluorine (mg/kg)**.
**How to fix it:** Enter a number ≥ 0 or leave the cell blank — blank is allowed and means "not stated". Common causes: a unit carried along (`12 g` instead of `12`) or text such as `n/a`.
On the decimal separator:
* **Excel** (`.xlsx`, `.xls`) — a cell formatted as a **number** always works, regardless of how it is displayed. A cell formatted as **text** holding `12,5` fails; format the column as a number in that case.
* **CSV with semicolons** — the decimal comma is recognised (`12,5`), provided the header row contains no further separator (comma, tab or `|`) — otherwise the semicolon is not recognised as the column separator.
* **CSV with commas** — here the value needs a dot (`12.5`).
### GTIN must be 8, 12, 13 or 14 digits
> GTIN must be 8, 12, 13 or 14 digits
**When does this happen?** In the **units import** the **GTIN** column has a different length or holds characters other than digits.
**How to fix it:** Enter the GTIN as a plain digit string of 8, 12, 13 or 14 characters — no hyphens, no spaces. Leaving it blank is allowed. In Excel, make sure the column is formatted as **text**: number formatting strips leading zeros and turns long GTINs into scientific notation.
### Market member states must be 2-letter ISO codes
> Market member states must be 2-letter ISO codes
**When does this happen?** In the **units import** the **Market Member States** column holds an entry that is not a two-letter country code — e.g. `Germany` instead of `DE`.
**How to fix it:** Use two-letter ISO country codes and separate several with `;` or `,` (e.g. `DE;FR;AT`). Case does not matter. An **empty** column is not an error — it imports as an empty list and is **not** backfilled from your PPWR default setting.
### Recycled content must be between 0 and 100%
> Recycled content must be between 0 and 100%
**When does this happen?** In the **components import** **Recycled Content (%)** is outside 0–100 or is not a number. A common cause: the share is entered as a fraction (`0.3`) instead of a percentage (`30`) — not an error as such, but almost always a data error.
**How to fix it:** Enter the percentage as a number between 0 and 100, without a `%` sign. Leaving it blank is allowed.
### Quantity must be a whole number of at least 1
> Quantity must be a whole number of at least 1
**When does this happen?** On the packaging bill of materials via the API the `quantity` field is 0 or negative.
**How to fix it:** Enter a whole number ≥ 1 — it states how often the component occurs in the unit. A **missing** value is not an error and means 1.
A **decimal** (`2.5`) or text does **not** produce this message but an untranslated English text such as `Invalid input: expected int, received number`. The meaning is the same: the quantity has to be a whole number.
## Business rules for components
### Recycled content needs a source and a method
> Recycled content needs a source and a method
**When does this happen?** **Recycled Content (%)** is greater than 0, but **Recycled Source** or **Recycled Method** is missing. A share of exactly 0 does not trigger the error — no evidence is needed then.
**How to fix it:** Fill both columns: **Recycled Source** (`pcr` = post-consumer or `pir` = post-industrial) and **Recycled Method** (`physical` or `mass_balance`). Without them the recycled share is unevidenced and must not feed a Declaration of Conformity.
### Food-contact components are also contact-sensitive
> Food-contact components are also contact-sensitive
**When does this happen?** **Food-contact** is set to "yes" but **Contact-sensitive** is not.
**How to fix it:** Set **Contact-sensitive** to `yes` as well. Food contact is, in substance, a special case of contact-sensitive — the combination "food-contact yes, contact-sensitive no" does not exist.
### A PFAS attestation only applies to food-contact components
> A PFAS attestation only applies to food-contact components
**When does this happen?** A PFAS column is filled although **Food-contact** is not set to "yes". Affected are **PFAS Compliant**, **PFAS Basis**, **PFAS Method**, **PFAS Sum (ppb)** and **Total Fluorine (mg/kg)**.
**How to fix it:** Either set **Food-contact** to `yes` (if the component really does have food contact) — or clear that row's PFAS columns. The Art. 5 PFAS limits only apply to food-contact packaging; a PFAS value on another component would be a statement without a legal basis.
**Heavy metals are not affected by this.** **Heavy Metals (mg/kg)** and **Heavy Metals Method** apply to **every** component and may be filled regardless of food contact.
### Claim basis missing
> Claim basis missing: provide a test report or supplier declaration (required once an Art. 5 value is given)
**When does this happen?** The row states an Art. 5 value without naming the matching claim basis. There are exactly two triggers:
* **Heavy Metals (mg/kg)** is filled but **Heavy Metals Basis** is missing or set to `not_substantiated`.
* **Food-contact** is `yes` **and** at least one of **PFAS Compliant**, **PFAS Sum (ppb)** or **Total Fluorine (mg/kg)** is filled, but **PFAS Basis** is missing or set to `not_substantiated`.
**How to fix it:** For the value in question, fill **Heavy Metals Basis** or **PFAS Basis** with `test_report` or `supplier_declaration`. `not_substantiated` is not a valid basis for a stated value. Alternatively leave the Art. 5 value blank in this file and add it later with its evidence.
Only what is **in the import row** counts — not what is stored in the platform. A row that only changes a name or notes and states no Art. 5 value is not blocked, even when the existing component has no claim basis.
## Matching and linking
### Duplicate key in file
> Duplicate key in file — first occurrence imported, this row skipped
**When does this happen?** The same matching key occurs more than once in **one** file (or in one API request):
| Import | Key that is duplicated |
| --------------------------------- | --------------------------------------- |
| Units | **Reference** |
| Components | **Code** |
| Article mapping (API) | **`specInternalRef` + `articleNumber`** |
| Packaging bill of materials (API) | **`specInternalRef` + `componentCode`** |
**How to fix it:** Merge the affected rows in your file into **one** row and import again. Important: the import does **not** merge them — the first row wins, every further one is skipped. Values that only appear in a later row are lost.
In the components import the **code alone** counts for this error — even when the two rows name different suppliers. To create the same code for two suppliers, import the second row in a separate file.
### Ambiguous supplier name
> Ambiguous supplier name '`{name}`' — matches more than one supplier; use the exact, unique company name
**When does this happen?** The name in the **Supplier** column matches **two or more** of your suppliers. The match is fuzzy (case, umlauts, punctuation and legal-form suffixes such as `GmbH` do not count), so two suppliers "Müller GmbH" and "Mueller AG" hit the same name. The import does not guess — the row is aborted without writing. This applies to the **components import** as well as the **units import**.
**How to fix it:** Enter the full company name that matches exactly one of your suppliers, or make the names unique in the supplier list. A name that matches **no** supplier is not an error: the record then lands without a supplier in your own inventory.
### Ambiguous component code
> Ambiguous component code — matches more than one component; add a Supplier column to disambiguate
**When does this happen?** The component code does not match one component unambiguously. There are two different triggers:
* **In the components import:** the row names **no** supplier (or one that does not resolve), and the code already exists in **a supplier's** inventory. The import then neither creates a second component in your own inventory nor updates the supplier's component on a guess — the row is aborted without writing.
* **In the Component Codes column of the units import and on the packaging bill of materials via the API:** the code matches **two or more** of your active components. Neither place has a supplier field, so there is nothing to distinguish them by — the oldest match is never linked. In the **Component Codes** column the **whole row** is aborted, so the unit is not written either.
**How to fix it:** In the **components import**, fill the **Supplier** column with the name **exactly as it is stored in the platform** — then the row matches that supplier's component unambiguously. If the component should belong to your own inventory, assign a code that is not taken instead.
In the **Component Codes** column and on the packaging bill of materials via the API there is no way to disambiguate in the file — the one fix is a **unique code**: rename the affected components to unique codes in the components list and import again.
Which key applies where is set out in [How the import matches](/en/ppwr/stammdaten/import#how-the-import-matches).
### No packaging unit with this reference
> No packaging unit with this reference
**When does this happen?** The reference points at no active packaging unit — the `specInternalRef` field on both the packaging bill of materials and the article mapping via the API. A **deleted** unit also counts as "does not exist".
**How to fix it:** Create the unit first — via the **units import** or manually — and import the links afterwards. Also check the spelling: the reference is compared character for character, `EIN-001` is not `ein-001`. If the unit was deleted, restore it in the **Packaging units** list via the filter for deleted records.
### No component with this code
> No component with this code
**When does this happen?** On the packaging bill of materials via the API the `componentCode` field points at a code for which no active component exists.
**How to fix it:** Create the component first via the **components import**, then the link. This import deliberately creates **no** components automatically — unlike the **Component Codes** column of the units import, which creates a placeholder component for an unknown code.
### No article with this number
> No article with this number
**When does this happen?** On the article mapping via the API there is no active article for the stated **internal article number**.
**How to fix it:** Create the article first (**Articles** list → **Import**) and send the mapping afterwards. The number is compared character for character. This interface creates no articles.
The **Article Numbers** link column of the units import behaves differently: there an unknown number is skipped **without an error row**. The result only names the **count** — "… article numbers were not found and were not linked." — not which ones.
### Internal reference already taken
> The internal reference is already used by another packaging unit. Assign a different internal reference and re-import.
**When does this happen?** Rarely. The units import normally recognises an existing reference and **updates** the existing unit (upsert). This message only appears when the unit with that reference came into being **between** the import's read and its write — typically through a colleague working in parallel or a second import running at the same time.
**How to fix it:** Simply import the file again — on the second run the import finds the now-existing unit and updates it. If the row is meant to create a **new, separate** unit, assign a different, free reference or leave the cell blank — Polygon One then assigns a free `PU-n` reference itself.
### Code already taken
> The code is already used by another component of the same supplier. Assign a different code and re-import.
**When does this happen?** Rarely. The components import normally recognises an existing code and **updates** the existing component (upsert); duplicate codes **inside** the file are reported as [Duplicate key in file](#duplicate-key-in-file). This message only appears when the collision arises **between** the import's read and its write — typically through a colleague working in parallel or a second import running at the same time. A row that changes the **supplier** of an existing component can collide this way too: the code has to be unique per supplier, and it may meanwhile be taken in the target group.
**How to fix it:** Simply import the file again — on the second run the import finds the now-existing component and updates it. If the row is meant to create a **new, separate** component (or on a collision caused by a supplier change), assign a different, free code. The same code for **different** suppliers is allowed.
### Could not link the component to the unit
> Could not link the component to the unit
**When does this happen?** Rarely. Unit and component were found, but writing the link failed — typically because one of the two records was deleted between the read and the write (for instance by a colleague working in parallel).
**How to fix it:** Check that unit and component still exist and import the file again. Links that already exist are not duplicated.
## Size rows
These messages only concern [size rows](/en/ppwr/stammdaten/import#sizes-as-extra-rows).
### This row mixes unit and size data
> This row mixes unit and size data. A size row may only repeat the packaging unit's own columns unchanged and must leave Component Codes empty; a Size Label needs a Size Reference of its own.
**When does this happen?** A row with its own **Size Reference** describes a size, not the unit. There are three triggers:
* It differs from the unit's row in one of the **unit's** columns: Name, Packaging Type, Role, Supplier, Packaging form, Recyclability Grade, Market Member States, Description & Intended Use, Own Brand, Modifies Conformity, Reusable.
* It carries something in **Component Codes** — the bill of materials belongs to the unit, not to a size.
* Conversely, the **unit row** carries a **Size Label** although it states no Size Reference of its own.
**How to fix it:** In size rows, repeat the unit's columns unchanged (or leave them blank) and fill only **Size Reference**, **Size Label**, **GTIN** and the dimensions. **Component Codes** belong exclusively in the unit row. If a value of the unit really is meant to differ, change it in the unit row — that row applies to every size.
**Where the row fails decides what happens.**
If the **unit row** is rejected during matching (e.g. an ambiguous supplier or an ambiguous component code), every size row sharing that reference fails with it — nothing is written. If, however, the unit row is already sorted out in the preview as an **invalid row** (for instance because of an unknown packaging type or a broken GTIN), its size rows carry on by themselves: they add to an existing unit — or, if the reference does not exist yet, they create the unit from the values of the **first size row**. So always check the preview first.
If only a **size row** fails, an **existing** unit and its other sizes are kept. On a unit that is **being created**, by contrast, a rejected size takes the whole unit with it.
### The size reference is already used
> The size reference is already used by another size or packaging unit. Assign a different reference and re-import.
**When does this happen?** The **Size Reference** has to be unique company-wide — it may be taken neither by a size of another unit nor by a unit's own internal **Reference**. The same Size Reference twice in one file triggers the message as well.
**How to fix it:** Assign a free reference. Prefixing it with the unit's reference (`PU-100-500G`) works well — that keeps the references apart for as long as you keep to the convention.
### This packaging unit already has the maximum number of sizes
> This packaging unit already has the maximum number of sizes. Remove one before adding another.
**When does this happen?** A packaging unit can carry at most **50** sizes, the primary one included. The file would exceed that limit.
**How to fix it:** Delete sizes you no longer need in the unit's **Sizes** card, or spread the variants across several packaging units.
### No size with this reference on this packaging unit
> No size with this reference on this packaging unit
**When does this happen?** On the packaging bill of materials or the article mapping via the API, a row names a **size** that does not exist on this unit. The reference is compared character for character, and it has to belong to **this** unit.
**How to fix it:** Create the size first — via the units import or in the **Sizes** card — and send the row again. If the row is meant to apply to the whole unit, omit the size field.
## Errors affecting the whole file
With these messages **not a single row** is imported. The message appears as a title with explanatory text, not as a row error.
### File format not supported
> **File format not supported** — This file can't be imported. Please upload a CSV or Excel file (.csv, .xlsx, .xls).
**When does this happen?** The chosen file has an extension other than `.csv`, `.xlsx` or `.xls` — often `.numbers`, `.ods`, `.txt` or `.pdf`.
**How to fix it:** Export or save the file as CSV or Excel and upload it again.
### File couldn't be read — differing column count
> **File couldn't be read** — Some rows have a different number of columns than the header. The most common cause is mixed delimiters (comma and semicolon) in the same file. Please re-export the file with a single, consistent delimiter and no blank rows.
**When does this happen?** In a CSV file, individual rows have more or fewer fields than the header row. The message names the affected row numbers.
**How to fix it:** Re-export the file with **one** consistent delimiter (in Excel: **Save as → CSV**) and remove blank rows at the end of the file. If a field itself contains the delimiter, it has to be quoted. The most robust route is the **Excel template** (`.xlsx`) — there is no delimiter problem there.
### File couldn't be read — unbalanced quotation marks
> **File couldn't be read** — Quotation marks in the file are unbalanced, so fields can't be separated reliably. Please check the highlighted rows or re-export the file.
**When does this happen?** In a CSV file a quotation mark is not closed, or a quotation mark inside text is not doubled. A field then "swallows" the rest of the row.
**How to fix it:** Check the rows named. A quotation mark **inside** a field has to be doubled (`"Plastic ""PET"""`). Easier: re-export the file from Excel — or use the Excel template in the first place.
### File couldn't be read — file could not be processed
> **File couldn't be read** — The file couldn't be processed. Please make sure it's a valid CSV or Excel file and re-export it if needed.
**When does this happen?** The file has the right extension but could not be opened — for example because it is damaged, password-protected, or in fact a different format with a renamed extension.
**How to fix it:** Open the file in Excel, remove any password protection and save it again as `.xlsx` or `.csv`.
There are further file errors for **GeoJSON** files ("Invalid GeoJSON file", "Not valid GeoJSON", "Geometry type not supported", …). Those occur exclusively on the **GeoJSON upload in your suppliers' data form** (EUDR module), not in the PPWR import.
## Notes above the error list
These two messages are **not** file errors: the file was read and the import ran. They stand **above** the error table in the result dialog and name the likely common cause of many row errors.
### Required columns not found
> **Required columns not found** — These required columns are missing from your file: `{columns}`. Add them with exactly these header names (see the template), or map your existing columns under Settings → CSV Imports.
**When does this happen?** The file is readable, but the import does not find one or more required columns — usually because the headers differ from the template (language, additions, typos) or because title rows sit above the header row. Because the column is missing, its value is empty in **every** row; below it you therefore usually see nothing but messages such as **"Code is required"**. The real error is the column, not the row.
**How to fix it:** Either align the column headers with the template — or map your own headers once under **Settings → CSV Imports** in the **Packaging units** or **Components** tab. Make sure the header row is the **first** row of the sheet.
### This looks like a different template
> **This looks like a different template** — The column headers in this file match the “`{template}`” import template. If that is what you filled in, import it from there instead.
**When does this happen?** Your file's headers match a **different** template from the one you are importing into — e.g. a filled-in units template in the components import. The hint names the detected template (**Packaging units**, **Components**, **Packaging quantities**, **Articles**, **Suppliers**, **Orders**, **BOM**).
**How to fix it:** Close the dialog and start the import where the named template belongs. The units and components templates have different required columns and are not interchangeable.
## A message that is not on this page
If the import result shows a technical-sounding English text (a database or constraint name, say), it is an unexpected error for which no translated message exists. The message is then passed through unchanged.
**How to fix it:** Try the import again — many of these cases are temporary. If the error persists, send us the message verbatim together with the **Identifier** from the error table via support.
Which matching key applies where.
Templates, columns and accepted values.