Troubleshooting

This page covers Magento 2-specific issues with KSeF Pro. For KSeF API error codes common to all platforms, see the error code reference.

Enable Debug Logging First

Before diagnosing any issue:

1. Go to Stores → Configuration → PlugKit → KSeF Pro → Advanced → Log Level
2. Set to Debug
3. Save and flush config cache: php bin/magento cache:clean config
4. Reproduce the issue
5. Review the log:

tail -100 var/log/ksefpl.log

The debug level records full HTTP request and response bodies for every KSeF API call, observer invocations, and rule engine decisions. Most issues can be diagnosed from this output alone.

Reset to Info after debugging.

Dependency Injection Compilation Errors

DI compilation errors are the most common Magento-specific issue. They occur after installation, upgrade, or when another extension conflicts with KSeF Pro's service contracts.

"Class ... Interceptor does not exist"

Symptoms: 500 error in Admin or storefront after installing or upgrading KSeF Pro. Error in var/log/exception.log.

Root cause: DI was not compiled after installation, or old generated code references class paths from a previous version.

Fix:

# Clear generated code
rm -rf generated/code/PlugKit
rm -rf generated/metadata
 
# Recompile
php bin/magento setup:di:compile
 
# Flush all caches including Redis
php bin/magento cache:flush

"Missing Interface Preference" Error

Symptoms: setup:di:compile fails with a message like Argument 1 passed to PlugKit\KsefPl\Model\...__construct() must implement interface ...

Root cause: Another extension has redefined a Magento core interface that KSeF Pro depends on (common with custom payment or order modules).

Fix: Identify the conflicting extension by disabling extensions one at a time:

php bin/magento module:disable <suspect-module>
php bin/magento setup:di:compile

Repeat until compilation succeeds, then re-enable the module and resolve the interface conflict in a di.xml preference.

DI Error on Adobe Commerce Cloud

setup:di:compile runs during the cloud build phase. DI errors appear in the build log:

magento-cloud activity:log --tail

If DI fails, the deployment rolls back automatically. Fix the conflict locally, push the corrected code, and monitor the next build. Do not attempt to patch generated code directly on the cloud server — the next deployment overwrites it.

Circular Dependency During Compilation

If setup:di:compile fails with a circular dependency involving a KSeF Pro class, break the cycle with a proxy injection in your custom module's di.xml:

<type name="MyVendor\MyModule\Model\MyService">
    <arguments>
        <argument name="ksefplService" xsi:type="object">
            PlugKit\KsefPl\Api\DocumentSubmissionServiceInterface\Proxy
        </argument>
    </arguments>
</type>

Proxies are lazy-instantiated and break circular dependency chains without changing behaviour.

Cron Not Running

Symptoms: Invoices accumulate in ksefpl_queue with PENDING status; no ksefpl_process_queue log entries after queue insertions.

Verify Job Registration

php bin/magento cron:run --group=default --dry-run 2>&1 | grep ksefpl

Expected output — all four jobs listed:

ksefpl_process_queue
ksefpl_poll_status
ksefpl_download_upo
ksefpl_retry_failed

If absent, the cron configuration was not loaded:

php bin/magento cache:clean config
php bin/magento cron:run --group=default

View Cron History in Admin

Go to System → Tools → Cron Schedule. Filter by Job Code containing ksefpl. Status meanings:

| Status | Meaning | |---|---| | success | Job ran and completed normally | | missed | Cron system is running behind schedule | | error | Job threw an exception — click "Messages" for detail | | pending | Scheduled but not yet run |

If you see only pending rows with no success, the system crontab is not running Magento cron. Verify:

crontab -l -u www-data | grep magento
# Should show: * * * * * php /var/www/magento/bin/magento cron:run --group=default

Redis Cron Lock Stuck

Magento uses cache-based locks to prevent concurrent cron job runs. If a job was killed mid-execution, the lock persists:

# Identify stuck locks
redis-cli KEYS "mage_cron_status_ksefpl_*"
 
# Clear them
redis-cli KEYS "mage_cron_status_ksefpl_*" | xargs redis-cli DEL

After clearing, trigger the cron manually:

php bin/magento cron:run --group=default

Force Queue Processing

For immediate relief:

php bin/magento ksefpl:process-queue
php bin/magento cron:run --group=default

Check var/log/ksefpl.log after running for queue processing entries.

Session Timeout Mid-Batch

Symptoms: Audit log shows records stuck in SUBMITTED status for more than 30 minutes. ksefpl_poll_status entries in the log show processingCode: 410 (session expired).

Diagnosis:

In System → Tools → Cron Schedule, look for ksefpl_process_queue runs with abnormally long execution times (over 25 minutes). In Sales → KSeF Pro → Audit Log, filter by SUBMITTED and check the submitted_at timestamp.

Immediate Resolution:

1. Filter audit log by SUBMITTED status — records older than 60 minutes have expired sessions
2. Select these records and click "Mark as failed"
3. Retry: "Retry selected"

Prevention:

Enable "One invoice per session" in Stores → Configuration → PlugKit → KSeF Pro → Advanced. Each invoice opens and closes its own session — timeout is impossible because sessions last under 5 seconds each. Recommended for stores with unpredictable batch processing times.

Alternatively, increase cron frequency:

# In stores configuration, set ksefpl_process_queue to */1 * * * *
php bin/magento cache:clean config

FA(2) XML Validation Failures (Error 20000)

Read the MF Validation Report

From Sales → KSeF Pro → Audit Log, expand the FAILED record and click "View MF validation report". The MF API returns a structured XML validation report pointing to the exact failing element.

Tax Rate Mapping Incomplete

The most common Magento-specific cause. Check for unmapped rules:

php bin/magento ksefpl:check-tax-mapping

Fix all NOT MAPPED entries in Stores → Configuration → PlugKit → KSeF Pro → Tax Rate Mapping.

Multi-Store Scope NIP Mismatch

If your store has multiple websites with different NIPs configured at website scope, confirm the effective NIP for the order's originating website:

php bin/magento config:show ksefpl/seller/nip --scope=websites --scope-code=<website_code>

If the result is empty, the website scope does not have a NIP configured — it falls back to Default scope. Explicitly set the NIP at website scope if needed.

Invoice Date Timezone

Magento stores created_at timestamps in UTC. KSeF Pro converts to Europe/Warsaw for <DataWystawienia>. If the Magento store timezone is misconfigured:

php bin/magento config:show general/locale/timezone
# Should return: Europe/Warsaw

An incorrect timezone shifts the invoice date for orders placed near midnight Polish time. Set to Europe/Warsaw in Stores → Configuration → General → General → Locale → Timezone.

Postal Code Format

KSeF rejects postal codes without a hyphen (e.g., 00123 must be 00-123). If the Seller Data postal code is missing the hyphen, the validation error appears in the <KodPocztowy> element. Fix the seller address in KSeF Pro configuration.

MAGE_KEY Changed (Token Unreadable)

Symptoms: The connection test fails with a decryption error. ksefpl:test-connection outputs: Unable to decrypt stored token.

Cause: MAGE_KEY in app/etc/env.php changed (database migration, environment clone, disaster recovery).

Fix:

# Verify the issue
php bin/magento ksefpl:test-connection

Re-enter the token in Stores → Configuration → PlugKit → KSeF Pro → KSeF Connection. Save configuration and test connection.

For Adobe Commerce Cloud, use environment variables to avoid this issue entirely:

magento-cloud variable:set --name=KSEFPL_API_TOKEN --value="your-token" --sensitive=true

Observer Not Firing on Invoice Save

Symptoms: Invoices are created but no entries appear in ksefpl_queue. Debug log shows no observer activity.

Diagnosis:

# Check the observer is registered
php bin/magento dev:di:info \
  "PlugKit\KsefPl\Observer\InvoiceSaveAfterObserver"

If the observer is listed as disabled or not found:

php bin/magento cache:flush
php bin/magento setup:di:compile

If another extension has disabled the sales_order_invoice_save_after event or rewrites Magento\Sales\Model\Order\Invoice, KSeF Pro's observer may not fire. Check for rewrites:

grep -r "sales_order_invoice_save_after" vendor/ app/code/ \
  --include="*.xml" | grep -v "PlugKit"

If another module is disabling this event, add KSeF Pro's observer with a higher sort order or contact the conflicting module's vendor.

Adobe Commerce Cloud-Specific Issues

DI Compilation Fails in Build Phase

magento-cloud activity:log --tail

Look for lines containing PlugKit in the build output. Common causes: Composer dependency version mismatch (another extension requires a different Magento version), or the module was added to composer.json without running composer update.

Fix:

# Local
composer update plugkit/module-ksefpl --with-dependencies
git add composer.lock
git commit -m "fix: update KSeF Pro lock file"
git push

UPO Files Not Persisting Across Deployments

The var/ directory is persisted on Adobe Commerce Cloud (mounted as a shared directory). UPO files stored under var/ksefpl/upo/ survive deployments. If files are disappearing:

magento-cloud mount:list
# Confirm var/ is listed as a mount

If var/ksefpl/ is being cleared by a custom deploy hook, add an exclusion for var/ksefpl/ in .magento.app.yaml.

Getting Support

Before opening a ticket at plugkit.io, collect:

# Magento and extension versions
php bin/magento --version
php bin/magento module:status PlugKit_KsefPl
 
# Recent KSeF Pro log (debug level active)
tail -200 var/log/ksefpl.log
 
# Queue state
php bin/magento ksefpl:queue-status
 
# Cron status for KSeF jobs
php bin/magento cron:run --group=default --dry-run 2>&1 | grep ksefpl
 
# DI compilation check
php bin/magento setup:di:compile 2>&1 | grep -i "plugkit\|ksef\|error"
 
# System info
php bin/magento info:all

Also include the audit log row export for the failing invoice (from Sales → KSeF Pro → Audit Log → expand the row → "Copy debug info").

Next Steps

• Review the changelog
• Back to configuration