Magento importfouten oplossen zonder dataverlies

Een import die op 98 procent blijft hangen, producten overslaat of ineens duizenden afbeeldingen mist, is geen klein beheerprobleem. Het raakt je assortiment, voorraad en verkoop direct. Magento importfouten oplossen begint daarom niet met opnieuw op ‘Importeren’ klikken, maar met vaststellen welk deel van de keten faalt: het bronbestand, de Magento-configuratie, de server of een koppeling met ERP, PIM of leverancier.

Bij een kleine catalogus kun je een fout nog handmatig herstellen. Bij duizenden SKU’s, meerdere storeviews en automatische voorraadupdates wordt dat snel risicovol. Dan wil je weten wat Magento precies afkeurt, waarom het gebeurt en hoe je een herhaling voorkomt.

Magento importfouten oplossen: lees de foutmelding letterlijk

Magento geeft tijdens en na een import meestal bruikbare signalen. Alleen staan die niet altijd op de plek waar je ze verwacht. Kijk eerst naar de validatie-uitkomst in het importscherm. Daar zie je vaak een regelnummer, SKU en foutcode. Is de import via een cronjob, API of maatwerkmodule uitgevoerd, controleer dan ook de applicatielogs en de logging van de koppeling.

De meest gemaakte fout is een CSV-bestand aanpassen op gevoel en opnieuw draaien. Daarmee kun je de oorspronkelijke oorzaak verbergen, terwijl het volgende bestand hetzelfde probleem opnieuw veroorzaakt. Pak liever één afgekeurde regel, zoek het betreffende product op en vergelijk de kolommen met een product dat wel zonder fout wordt verwerkt.

Let vooral op deze vier vragen:

• Is de SKU uniek en exact gelijk aan de bestaande SKU die je wilt bijwerken?
• Bestaat de attribuutcode in Magento en accepteert die attribuutset deze waarde?
• Is het formaat van de waarde geldig, bijvoorbeeld bij prijs, datum, voorraad of dropdown-optie?
• Komt de kolomkop exact overeen met wat Magento of de importextensie verwacht?

Een foutmelding als ‘Value is not allowed’ wijst meestal op een dropdownwaarde die niet bestaat. ‘URL key already exists’ betekent vaak dat twee producten dezelfde URL-key krijgen, of dat een oud product deze URL nog bezet. ‘Product with SKU already exists’ kan juist betekenen dat de gekozen importgedraging niet past bij je doel: toevoegen, bijwerken of vervangen zijn drie verschillende acties.

Begin bij het CSV-bestand, niet bij Magento

Een groot deel van de importproblemen ontstaat voordat Magento het bestand überhaupt leest. Excel is daarbij geregeld de boosdoener. Het programma verandert soms voorloopnullen, datums, scheidingstekens en tekencodering zonder dat dit direct opvalt. Een SKU als 000123 wordt dan 123. Voor Magento zijn dat twee verschillende producten.

Exporteer daarom bij voorkeur als UTF-8 CSV. Controleer ook welk scheidingsteken jouw omgeving verwacht. Nederlandse Excel-installaties gebruiken vaak een puntkomma, terwijl veel importprofielen een komma verwachten. Open het bestand eens in een platte teksteditor. Dan zie je direct of kolommen onverwacht verschuiven of velden dubbele aanhalingstekens bevatten.

Komma’s, enters en quotes in productomschrijvingen verdienen extra aandacht. Een regeleinde in een omschrijving is prima, mits het veld correct tussen quotes staat. Eén ontbrekende quote kan ervoor zorgen dat alle regels daaronder verkeerd worden ingelezen. De fout lijkt dan bij product 842 te zitten, terwijl de werkelijke fout drie regels eerder staat.

Werk ook met een kleine testimport. Neem vijf tot tien producten mee, inclusief een simpel product, een configurable product, een product met afbeeldingen en een product met afwijkende attributen. Slaagt die test, dan is een volledige import een stuk veiliger. Dat kost een paar minuten en voorkomt dat je achteraf honderden producten moet herstellen.

Attributen en attribuutsets: klein verschil, grote gevolgen

Magento is streng op productdata, en terecht. Een attribuutlabel is niet hetzelfde als een attribuutcode. ‘Merk’ kan in de backend zichtbaar zijn, terwijl de technische code brand of manufacturer is. Een import die de zichtbare naam gebruikt, faalt of negeert de kolom afhankelijk van de gebruikte methode.

Dropdown- en multiselectattributen zijn nog gevoeliger. Magento verwacht meestal een bestaande optie. Staat er in je PIM ‘Donker blauw’ en kent Magento alleen ‘Donkerblauw’, dan is dat geen cosmetisch verschil. De import kan de waarde afkeuren, leeg laten of een nieuw gedrag veroorzaken dat je niet wilt.

Leg daarom per koppeling vast welke waarden zijn toegestaan. Bij een PIM- of ERP-integratie is een vertalingstabel vaak de nette oplossing. Je bron mag dan bijvoorbeeld interne codes gebruiken, terwijl Magento de juiste commerciële waarde ontvangt. Dat is betrouwbaarder dan medewerkers vragen om elke schrijfwijze handmatig gelijk te trekken.

Ook de attribuutset moet kloppen. Importeer je een waarde voor een attribuut dat niet in de gekozen set zit, dan kan Magento die niet verwerken zoals verwacht. Dit zie je vaak wanneer een assortiment wordt uitgebreid met een nieuw producttype, maar de technische inrichting nog achterloopt.

Afbeeldingen die niet meekomen hebben vaak een serveroorzaak

Bij media-imports ligt het probleem niet altijd in de productregel. Magento moet het afbeeldingsbestand kunnen vinden, lezen en opslaan. Controleer dus of de bestandsnaam in de CSV exact overeenkomt met het fysieke bestand. Hoofdletters, extensies en spaties kunnen op Linux-servers verschil maken.

Gebruik geen losse lokale paden zoals C:\afbeeldingen\product.jpg. Magento verwacht meestal een pad binnen de aangewezen importdirectory of een publiek bereikbare bron, afhankelijk van de gekozen importoplossing. Controleer daarnaast bestandsrechten, vrije schijfruimte en de maximale uploadlimieten van PHP en de webserver.

Een import met 20.000 zware productfoto’s vraagt iets anders van je platform dan een update van honderd prijzen. Te kleine PHP memory limits, korte maximale uitvoeringstijden of een drukke database kunnen het proces onderbreken. Meer capaciteit geven is soms nodig, maar niet altijd de beste eerste stap. Het verkleinen en optimaliseren van bronafbeeldingen is vaak goedkoper en sneller voor je storefront.

Draait de import via een externe feed, controleer dan ook de beschikbaarheid van die bron. Time-outs, tijdelijke blokkades of een gewijzigde URL-structuur zorgen ervoor dat Magento afbeeldingen niet kan ophalen. Leg mislukte downloads vast in logs, zodat je niet pas dagen later ontdekt dat een nieuwe collectie zonder beeld live staat.

Na een geslaagde import kan Magento nog achterlopen

‘Import completed successfully’ betekent alleen dat Magento de data heeft geaccepteerd. Het betekent niet automatisch dat klanten die data al correct zien. Magento werkt met indexers en caching. Prijzen, categorieposities, zoekresultaten en voorraadstatus kunnen na een grote import nog een verouderde weergave tonen.

Controleer daarom na de import of relevante indexers zijn bijgewerkt. Bij grote wijzigingen is de juiste indexmodus bepalend. Een realtime update kan bij veel mutaties de shop vertragen. Een geplande update is rustiger voor de storefront, maar vraagt wel om een goed draaiende cron. Het hangt dus af van de frequentie, de omvang van je mutaties en hoe actueel je voorraad moet zijn.

Wis niet blind alle caches als een product ontbreekt. Kijk eerst of het product actief is, op voorraad staat, aan de juiste website is gekoppeld en zichtbaar is in de juiste catalogusstatus. Bij multi-store Magento-omgevingen gaat het vaak mis op scope: een prijs of omschrijving is geïmporteerd voor de standaardweergave, terwijl de Nederlandse storeview een eigen waarde verwacht.

Bij configurable producten is de relatie met de onderliggende simple producten een extra controlepunt. Het hoofdproduct kan correct bestaan, maar zonder geldige configuraties of voorraad in de varianten is het voor de klant niet verkoopbaar. Test daarom altijd een productpagina, categoriepagina, zoekresultaat en winkelmandje. Backend-data die er goed uitziet, is niet voldoende.

Voorkom herhaling met een importproces dat te controleren is

Handmatig importeren vanuit een gedeelde map werkt zolang één persoon alles weet. Zodra meerdere collega’s, leveranciers of systemen data aanleveren, heb je afspraken en controles nodig. Houd bronbestanden versieerbaar, maak onderscheid tussen test en productie en leg per import vast hoeveel producten zijn toegevoegd, bijgewerkt, overgeslagen en afgekeurd.

Voor terugkerende imports is automatisering logisch, maar alleen als de foutafhandeling net zo goed is ingericht als de import zelf. Een nachtelijke ERP-koppeling zonder meldingen is geen automatisering, maar uitgestelde onzekerheid. Laat afwijkingen melden: een onbekende SKU, een prijs van nul euro, een voorraad die plotseling naar nul gaat of een ongewoon hoog aantal fouten moet direct zichtbaar zijn.

Bij bedrijfskritische koppelingen bouwen we bij Disrex liever validaties vóór de import dan herstelwerk erna. Denk aan SKU-controles, verplichte velden, waardevertalingen, een dry-run en duidelijke foutmeldingen voor het operationele team. Dat maakt een integratie minder afhankelijk van één developer en geeft je team grip op de catalogus.

De beste import is niet de import die één keer zonder fout draait. Het is het proces waarin een afwijking vroeg wordt gezien, begrijpelijk wordt gemeld en veilig kan worden hersteld - voordat je klant merkt dat een product, prijs of voorraadstand niet klopt.