Overview
This page leads from a symptom to cause and solution, for the product export as of version 12.7.0 of the bundle and the product import as of version 3.0.0 of the plugin. The behaviour in detail is described on the pages "Product export: FAQ", "Product import: FAQ" and "Frequently Asked Questions".
Messages are quoted in their original wording. The messages of the import are written to the journal (.done) and to the import report by mail (see "What does the journal show?"), <id> stands for the Pimcore ID of the entry.
Export in Pimcore
The export files are very large
| Cause | Solution |
|---|
Many languages are exported. Without supported_languages, the product adapters export all languages enabled in Pimcore that are not in disabled_languages | Limit the languages per export target with supported_languages, given as Pimcore languages (e.g. de, en). language_mapping only defines the Shopware locale and does not limit languages (see "Configure Language Mapping" and "How do I export only some languages?") |
| Localized fields return their fallback values in the export. Languages without an own value therefore contain the texts of the fallback language, e.g. complete descriptions | Exclude languages that are not needed via supported_languages |
supported_languages only affects product adapters (ProductAdapterAbstract). Other adapters that use e.g. translationHelper()->mapTranslations() export all enabled languages | Exclude languages for all export targets via disabled_languages (see "Disable Languages") |
A full export was created (file name <target>-full-<date>.json), via the option "Export full data (No delta)" or --skip-delta. For export targets with has_delta_management: false, the queue runs every export as a full export | Use a delta export (file name <target>-delta-<date>.json) and check has_delta_management of the export target (see "Configure Target Systems") |
The delta export only compares with exports in the status "Successful". Pimcore sets this status once it has processed the .done file with the resolution success. Until then, every delta export contains all changes since the last successful export | See "The import report does not arrive" |
buildProduct() returns different values on every run, the entries are always considered changed | See "A product is transferred in every delta export" |
| Variants are part of the entry of their main product. If a variant changes, the main product including all variants is transferred | Expected behaviour (see "How does the delta export detect changes?") |
A full export contains the cross-selling of all products in the package cross-selling, a delta export only that of the exported products | Use a delta export (see "Delta export") |
The export was created via CLI with --pretty | Use --pretty for analysis only, exports via the queue are not formatted |
Dependent adapters are exported automatically, the product adapter e.g. with the adapters attributes and attribute-values, if they are registered | Expected behaviour (see "Dependencies between Export Adapters") |
The export aborts with "Unknown key"
Unknown key "<key>" in the product entry of object <ID> (<adapter>). Return [...parent::getAllowedProductKeys(), '<key>'] from getAllowedProductKeys() to allow it or null to disable the check
| Cause | Solution |
|---|
Typo or key in camelCase (productNumber) in buildProduct() | Correct the key (see "Export JSON contract") |
| Own key, e.g. for an own product module | Extend getAllowedProductKeys() or getAllowedTranslationKeys() or return null (see "Why does the export abort with "Unknown key"?") |
translations.<locale> is not an array (The translation "translations.<locale>" of object <ID> (<adapter>) must be an array) | Build the translations via prepareTranslations() |
The ExportException aborts the whole export run and appears in the export report. For a single object, twocream:shopware-connector:preview-product outputs the message without stack trace (see "Preview product").
The export does not start or fails
| Cause | Solution |
|---|
The queue is not processed. Exports from the admin interface are run by twocream:shopware-connector:queue | Set up the cron job * * * * * php /var/www/html/bin/console twocream:shopware-connector:queue (see "Queue System") |
| The export is scheduled for a later point in time | The export starts with the first run of the queue after the scheduled point in time |
Another export is running (The command is already running.) | The export stays in the queue and is run in a later run |
The export directory is not an absolute path or does not exist (Target directory needs to be an absolute path (Path: "…"), Target directory needs to exist (Path: "…")) | Correct export_directory of the export target or create the directory |
buildProduct() throws an exception | Check the affected object with preview-product (see "Preview product") |
A language is missing in the export
| Cause | Solution |
|---|
The Pimcore language is not in supported_languages of the export target, is not enabled or is in disabled_languages | Check the configuration (see "Why is a language missing in the export?") |
supported_languages contains Shopware locales (e.g. de_DE) or typos. If the list contains no enabled Pimcore language, the entries have no translations and Shopware skips simple products and main products | Use Pimcore languages. preview-product warns with The supported languages "<languages>" are no enabled Pimcore languages and are not exported or No supported language is enabled in Pimcore, the product has no translations |
The callback of prepareTranslations() returns null for the language | Check the callback, it receives the Pimcore language (e.g. de) |
A delta export does not contain a change
| Cause | Solution |
|---|
The change does not affect the result of buildProduct(). The delta export compares a checksum of the entry, not the modification date of the object | Return the value in buildProduct(), check the result with preview-product (see "How does the delta export detect changes?") |
Only the cross-selling has changed and buildProduct() does not return cross-selling-checksum | Return 'cross-selling-checksum' => $this->getCrossSellingChecksum($product) |
The object is not located below the source_folder_ids of the adapter or is excluded in prepareListingConditions() | Check the configuration of the adapter (see "Configure Adapters") |
| Shopware should receive the complete state of Pimcore, e.g. after skipped batches | Run a full export: option "Export full data (No delta)" or --skip-delta (see "Commands") |
A product is transferred in every delta export
| Cause | Solution |
|---|
buildProduct() returns different values per run, e.g. a timestamp or a changing order of relations | Return identical values for unchanged data (see "Why is a product transferred in every delta export?") |
| The import reports a warning or an error for the entry. Pimcore removes the checksum of such entries so that the message appears again in the next export | Fix the cause of the message in the journal, e.g. a too long text or an unknown custom field |
| The previous export does not have the status "Successful" | See "The import report does not arrive" |
The cross-selling is missing in the export
| Cause | Solution |
|---|
The adapter uses the CrossSellingTrait but does not implement the CrossSellingProviderInterface | Implement the interface |
buildProduct() calls neither getCrossSellingChecksum() nor prepareCrossSelling() | Return 'cross-selling-checksum' => $this->getCrossSellingChecksum($product) |
| Delta export: the package only contains the cross-selling of the products exported in this run including their variants, never for deleted products | Expected behaviour, run a full export for the cross-selling of all products |
See "Why is the cross-selling missing in the export?" and "Step 8: Cross-selling".
Variants are exported twice
Variant objects are part of the listing and appear as an own entry and additionally in variants of their main product. Exclude variants from the listing via prepareListingConditions() (see "Why are variants exported twice?").
Assets are missing in the asset directory
| Cause | Solution |
|---|
transfer > adapter is pimcore_asset and asset_transfer is not configured. The assets are then also stored via the PimcoreAssetTransferAdapter, which is not suitable for this | Configure asset_transfer with an own adapter, e.g. nfs (see "JSON files and assets") |
The asset has already been copied for the export target. The bundle records copied assets in the table twocream_asset_export_journal and only copies an asset again after a change (modification date), even if the file is missing in the target | Save the asset in Pimcore again or remove the entries of the asset from twocream_asset_export_journal |
The file could not be copied, the export report shows e.g. Asset <path> could not be copied to the asset directory | Check the source file in Pimcore as well as asset_directory and its write permissions |
Transfer
The export file is not imported in Shopware
| Cause | Solution |
|---|
The messenger transport json is not consumed | Set up the cron job messenger:consume json (see "Messenger Transport") |
The file is not located in the import directory of Shopware. Shopware only searches *.json directly in the import directory, not in subdirectories | Align the import directory (see "Configuration") with export_directory and the directory resolver of the export target (see "Determine storage directories using a directory resolver") |
| The file is younger than 30 seconds | Except in the environment dev, files are only processed after 30 seconds |
The worker reports Import directory is not configured. Did you forget the plugin configuration? or Directory is not writable: "<path>" | Configure the import directory or set the write permissions |
For testing, a single file can be imported with php bin/console twocream:json:import <file> (see "Commands").
The file remains as .work file
Shopware renames the file to .work before the import and writes the .done file after the import. If a .work file without .done file remains after the import has ended, the worker was aborted during the import (e.g. by the memory limit). The file is not processed again, since Shopware only picks up *.json.
Check the cause in the log of the worker and rename the file to .json or run the export again. Since the export does not receive the status "Successful", a delta export contains the changes since the last successful export again.
The import report does not arrive
Until Pimcore has processed the .done file, the export remains in the status "Exported" and the delta export keeps comparing with the last successful export.
| Cause | Solution |
|---|
Pimcore processes .done files when twocream:shopware-connector:queue runs | Set up the cron job of the queue (see "Queue System") |
The .done file is younger than 60 seconds | Except in the environments dev and development, .done files are only processed after 60 seconds |
The .done file is not located in a directory that Pimcore searches (resolveDoneDirectories() of the directory resolver, by default export_directory) | Point the import directory of Shopware and export_directory to the same directory |
After processing, the export receives the status "Successful" for the resolution success, otherwise "Failed".
Import in Shopware
The import aborts with "Detected unknown package"
No module is registered for a package of the file, e.g. Detected unknown package "products". The file ends with the resolution error, the following packages are not imported.
| Cause | Solution |
|---|
The ProductModule is not registered by the plugin | Register the module or a subclass with the service tag twocream_json_importer.module (see "Registering the product module") |
| The module for an own package is missing | Register the module (see "Register the module") |
An own import module is ignored
| Cause | Solution |
|---|
The subclass of a module registered by the plugin (PropertyGroupModule, PropertyGroupOptionModule, CrossSellingModule, CategoryAssignmentModule) is additionally registered with the service tag. The first module of a package is used | Register the subclass as decorator (decorates) without an own tag (see "Replace a module of the plugin") |
Several modules are registered for the package products | Register only one module |
A product is missing in Shopware
| Message or cause | Solution |
|---|
Field "<field>" is not valid in record <id> | Deliver the required data (see "Which data is required?") |
Product has no translations (ID: "<id>") | Deliver translations, check supported_languages (see "A language is missing in the export") |
Product skipped because a new product needs a name in the system language (ID: "<id>") | Deliver a name in the system language and check the locale keys (see "Which locales are accepted?") |
Tax rate can not be detected (ID: "<id>", Tax: "<tax>") | Create the tax rate in Shopware, the import does not create taxes |
… is already used in Shopware by product <id> (UUID: "…") or … is already used by record <id> in this import file | Release the product number in Shopware or correct it in the source system (see "What happens if the product number already belongs to another product in Shopware?") |
Product is a represent but has no valid variant (ID: "<id>") | Check the variants or let getVariants() return null so that the product is exported as simple product |
Batch was skipped because it could not be written, affected records: … | See "The file ends with success, but data is missing" |
No message, the entry is not in the file: the object is not located below the source_folder_ids, is unpublished, isExportable() returns false or it is unchanged since the last successful delta export | Check the object with preview-product (see "Preview product") |
The file ends with success, but data is missing
Skipped entries and batches do not change the resolution, they only appear as warning or error in the journal (see "Which resolution does a file with skipped entries have?"). For monitoring, the messages have to be evaluated.
| Message | Solution |
|---|
WARNING per entry, e.g. Field "<field>" is not valid in record <id> | See "A product is missing in Shopware" |
Batch was skipped because it could not be written, affected records: … Cause: … | The batch (getBatchSize(), by default 75 main products including variants) was rolled back completely. The cause names entry and field. Correct the data in the source system and export the named entries again (see "What happens if a batch cannot be written?") |
The journal reports "Batch was written, but post-processing failed"
The data is written in Shopware, afterwards a listener of the write event threw an exception (e.g. a subscriber of another plugin). Fix the cause from the message, reindex with dal:refresh:index if necessary (see "What does "Batch was written, but post-processing failed" mean?").
A value is not written in Shopware
| Message or cause | Solution |
|---|
| The key is missing in the entry, a simple key then keeps its previous value | Deliver the key, null writes an empty value (see "What is the difference between a missing key and null?") |
Custom field "<path>/<name>" is not available for products in Shopware, it is not written … | The name has to be an active custom field of a set that is assigned to products (see "What happens with an unknown custom field or an invalid value?") |
Custom field "<path>/<name>" was not written because value … is not valid for the type "<type>" … | Deliver a value matching the type, for select the message names the options |
| Invalid number, boolean or date, the warning names the field | Correct the value, the previous value is kept (see "Adjusted and not written values") |
Field "<field>" was truncated to <n> characters (length: <m>) | The text is longer than the Shopware field and was truncated |
The translation key is not contained in getProductTranslationKeyMap() | Add the key in the product module (see "Why is a translation key not written in Shopware?") |
| The key of the product extension is not mapped | See "Why is no product extension written?" |
Canonical product "<uuid>" is deactivated in this import, field is not written … or … is neither available in Shopware nor written in this import, field is not written … or … is the product itself, field is not written … | A canonical product must exist in Shopware or be written in the import, must not be the product itself and must not be deactivated by this import (see "How is the canonical product delivered?") |
CMS page "<uuid>" is not a product page layout (type: "<type>"), field is not written … or CMS page … is not available in Shopware, field is not written … | Deliver the UUID of an existing CMS layout of the type product_detail (see "How are the CMS page and the feature set delivered?") |
Feature set … is not available in Shopware, field is not written … | Deliver the UUID of an existing feature set |
Purchase price … is not valid (net and gross numeric, not negative), field is not written … | Deliver purchase-price as {net, gross} with numeric, not negative values |
Field "variant-listing-config" is only supported for main products, it is not written … or Main variant … is not a valid variant of this product in this import, it is not set … | Deliver variant-listing-config for main products only, the main variant must be a valid variant of the entry (see "How is the variant listing configured?") |
The import takes a long time
| Cause | Solution |
|---|
| Full exports are imported | Use a delta export (see "The export files are very large") |
| Many batches fail. After every failed batch, the cached IDs are reloaded | Fix the causes of the errors (see "Is the import suitable for large catalogues?") |
After every file, the import runs cache:clear, unless a module of the file implements the SkipCacheClearInterface | Mark modules after whose import the cache does not have to be cleared with Twocream\JsonImporter\Core\System\Import\Interface\SkipCacheClearInterface |
| The batch size does not fit the catalogue | Override getBatchSize() (default 75) in the product module |
Result in the shop
A product is not visible in the shop or has no rule prices
A language is missing in the shop
| Cause | Solution |
|---|
| The language is already missing in the export | See "A language is missing in the export" |
The Pimcore language has no entry in language_mapping and is exported under its Pimcore key (e.g. fr). By default, Shopware only maps de => de_DE and en => en_GB, other keys without a matching Shopware language are ignored | Add language_mapping, e.g. fr: 'fr_FR' (see "Configure Language Mapping"), or adjust the mapping via the LocaleMappingEvent |
The locale does not match the language in Shopware, e.g. en is delivered as en_GB, but the Shopware language uses en-US. Shopware compares with the translation code of the language (hyphen as underscore) | Adjust the locale in language_mapping to the Shopware language, e.g. en: 'en_US' |
The locale key contains a hyphen (e.g. de-DE) and is ignored | Deliver the locale with underscore (see "Which locales are accepted?") |
Properties, visibilities or rule prices were removed
Shopware brings properties, visibilities, prices and for variants options exactly to the state of the file on every delivery, the source system is leading.
| Cause | Solution |
|---|
The key is missing or [], all existing relations of this kind are removed | Deliver the relations completely on every delivery and maintain them in Pimcore only (see "When are relations cleaned up in Shopware?") |
| A market or a rule cannot be resolved, existing entries outside the resolved set are removed anyway | Check the hooks getSalesChannelIdByMarket() and getRuleIdByMarket() |
| A variant without these keys loses its own entries and inherits the values of the main product | Deliver the own relations of the variant (see "What happens if visibilities, properties or prices are missing?") |
Products are deactivated or activated unexpectedly
A variant does not inherit a value or inherits it unintentionally
| Cause | Solution |
|---|
| The key is missing for the variant, a missing key keeps the previous value of the variant | Return null for the variant, e.g. 'tax' => $mainProduct ? null : 19 |
The variant returns null and therefore inherits the value of the main product | Return the own value of the variant |
The variant returns no translations and keeps its previous names | Always return translations, name: null inherits the name of the main product |
See "How does a variant inherit a value of its main product?" and "What do variants inherit from the main product?".
A product is missing in a category
| Message or cause | Solution |
|---|
No category in Shopware has the delivered identifier in twocream_category_extension, or it is located outside of getRootCategoryId() | Align the identifier in Pimcore (getCategoryIdentifier()) and Shopware (see "Category assignments") |
| The identifier of the category object is empty, the object is transferred as deleted | Maintain the identifier (see "Step 9: Category assignments") |
Product is not available in Shopware (ID: "<id>") | The product does not exist in Shopware, e.g. because it was skipped (see "A product is missing in Shopware") |