Troubleshooting

This page covers the most common error scenarios encountered when running KSeF Pro for PrestaShop, along with root causes and exact resolution steps.

Enable Debug Logging First

Before diagnosing any issue:

Go to KSeF Pro → Configuration → Advanced → Logging Level
Set to Debug
Save configuration
Reproduce the issue (trigger an order status change or use "Retry" in the audit log)
Check the log: var/logs/ksefpl.log

The Debug level records full HTTP request and response bodies for every KSeF API call, including the raw error response from the Ministry of Finance servers. Most issues can be diagnosed from this log alone.

Reset to Error or Info after debugging — Debug logging generates several kilobytes per API call and fills disk quickly on busy stores.

KSeF API Error Code Reference

When the Ministry of Finance API rejects a request, it returns a structured error object. KSeF Pro logs the full error in the audit log detail row and in ksefpl.log.

| HTTP Code | KSeF Code | Meaning | Fix | |---|---|---|---| | 400 | 20000 | Invalid FA(2) XML structure or schema violation | Check XML preview; confirm all required elements present | | 400 | 20100 | NIP mismatch between token and <Podmiot1> | Verify seller NIP in Seller Data matches the NIP on the token | | 400 | 20200 | Invalid date format in <DataWystawienia> | Verify server timezone is Europe/Warsaw | | 400 | 20300 | Invalid VAT rate code in <P_12> | Check tax rate mapping — unmapped rule defaulted incorrectly | | 401 | 10000 | Session token expired or revoked | Generate a new token on the KSeF portal | | 401 | 10100 | Challenge signature mismatch | OpenSSL issue or token has trailing whitespace — see Signing Failures | | 403 | 30000 | Insufficient token scope | Regenerate token with invoice_write and invoice_read scopes | | 409 | 40000 | Duplicate invoice reference — already submitted | Check audit log for existing KSeF-ID; do not re-submit | | 503 | — | MF server temporarily unavailable | Transient — retries automatically; check status.ksef.mf.gov.pl |

XML Validation Failures (Error 20000)

FA(2) XML validation failures are the most common class of error. The MF schema is strict — missing optional elements cause rejections when mandatory combinations are not met.

Read the Validation Report

From the audit log, expand the failed record and click "View XML error detail". The MF API returns a structured validation report with the path of the failing element.

Common XML Failure Causes

Missing buyer NIP on B2B orders

If a B2B order has no NIP stored, KSeF Pro falls back to BRAK in <Podmiot2>. Some KSeF configurations reject this for orders above certain VAT thresholds. Fix: enable "Require NIP for B2B checkout" in Invoice Settings. Existing orders without NIP must be corrected manually in the order before re-submission.

Tax rate code not mapped

If a PrestaShop tax rule is not mapped to a Polish VAT code, KSeF Pro warns in the log and may default incorrectly. Navigate to Invoice Settings → Tax Rate Mapping and map every active tax rule. After fixing, preview the XML for a test order before retrying.

Invalid currency element

Orders in currencies where KSeF Pro cannot fetch an NBP rate (uncommon currencies) fail with a malformed <KursWaluty> element. Set a manual fallback rate in Advanced → Currency Fallback.

Date format error (20200)

The FA(2) <DataWystawienia> must be in YYYY-MM-DD format, Europe/Warsaw timezone. If your PHP server timezone is set to UTC, the date may be offset. Verify:

php -r "echo date_default_timezone_get();"

If the output is not Europe/Warsaw, set the timezone in your PHP configuration (php.ini: date.timezone = Europe/Warsaw) or add it to PrestaShop's .htaccess.

NIP Mismatch (Error 20100)

The NIP in KSeF Pro Seller Data does not match the NIP registered on the KSeF API token.

Resolution:

Log in to the KSeF portal and view the token details
Note the exact NIP associated with the token
In KSeF Pro → Seller Data, update the NIP to match exactly (no dashes, no spaces, no PL prefix)
Click "Verify Token" — a green indicator confirms the match

This error also occurs if you generate a token for one company and enter the NIP of a different company in KSeF Pro configuration. Each token is tied to a single NIP at generation time.

Signing Failures (Error 10100)

XAdES-BES signing failures mean the HMAC-SHA256 signature computed by KSeF Pro does not match what the MF server expects.

Verify OpenSSL

php -m | grep openssl
php -r "echo phpversion('openssl');"

OpenSSL must be listed. If absent, contact your hosting provider.

php -r "echo openssl_error_string();"

Any output indicates an OpenSSL error state. Contact your hosting provider.

Check for Whitespace in Token

Copy your token from the KSeF portal again directly into KSeF Pro configuration (do not paste through a text editor that may add line breaks or spaces). The token field trims leading/trailing whitespace on save — confirm by saving and immediately re-opening the configuration screen to see the stored value length.

OpenSSL 3.2+ Compatibility

OpenSSL 3.2 deprecated some digest algorithm references. If you are on PHP 8.2+ with OpenSSL 3.2+ and see signing failures, update KSeF Pro to version 1.3.2 or later — this version addresses the OpenSSL 3.2 breaking change.

Session Timeout Errors

Symptoms: Audit log shows records stuck in SUBMITTED status for more than 30 minutes with no UPO.

Root cause: KSeF sessions expire after 30 minutes of inactivity. If your server's background processing is slow or stalled, the session may expire between the submit and close steps.

Resolution:

In the audit log, filter by SUBMITTED status
Records older than 60 minutes have expired sessions — invoices were not accepted
Select these records and click "Mark as failed"
Fix the underlying processing issue (see cron/background process below)
Retry submission from the audit log

Prevention: In Advanced → Retry Policy, enable "Close session immediately after each invoice". This trades throughput (one session per invoice instead of batching) for reliability — session timeout becomes impossible because each session closes within seconds of opening.

Cron / Background Process Not Running

Symptoms: Orders reach the trigger status but no audit log entries appear. The PENDING queue grows but nothing processes.

Diagnosis:

# Check PrestaShop cron is configured
crontab -l | grep prestashop
 
# Test the PrestaShop cron manually
php /path/to/prestashop/bin/console prestashop:cron:run
 
# Check the cron log
tail -50 /var/logs/ksefpl.log

Fix: Add the standard PrestaShop cron entry:

* * * * * php /path/to/prestashop/bin/console prestashop:cron:run >> /var/logs/prestashop-cron.log 2>&1

For shared hosting environments without cron access, enable "Synchronous processing" in KSeF Pro → Advanced. In synchronous mode, invoice submission happens during the order status change request (blocking the admin panel response briefly) rather than in a background process.

HPOS Compatibility

Symptoms: KSeF Pro does not detect order status changes after migrating to PrestaShop 9.x HPOS.

Fix:

Confirm HPOS is enabled: Advanced Parameters → Experimental → Use new storage
In KSeF Pro Advanced tab, enable "HPOS compatibility mode"
Save — this re-registers the order status hooks for the HPOS event system

If the option is already enabled but issues persist, disable it, save, re-enable it, and save again to force hook re-registration.

Module Hook Conflicts

Symptoms: KSeF Pro fires before order data (e.g. NIP) is fully committed by another module, resulting in invoices without buyer NIP.

Diagnosis: Enable Debug logging and check ksefpl.log for the order in question. Look for the timestamp of the KSeF Pro hook execution versus when the NIP is written to the order.

Fix: In Advanced → Hook Priority, increase KSeF Pro's hook priority number (higher number = later execution). Setting to 100 typically places KSeF Pro after all other modules:

Go to KSeF Pro → Configuration → Advanced
Set Hook Priority to 100
Save and test with a new order

Firewall / Connectivity Issues

Symptoms: All API calls fail with cURL error 7: Failed to connect or SSL errors.

Test connectivity from your server:

curl -v https://ksef-test.mf.gov.pl 2>&1 | grep -E "Connected|SSL|certificate|error"

Expected: Connected to ksef-test.mf.gov.pl and SSL connection using TLSv1.2/1.3.

If you see Connection refused or timeout, your server's outbound connections to the MF servers are blocked. Contact your hosting provider and request that ksef-test.mf.gov.pl and ksef.mf.gov.pl on port 443 are whitelisted.

If you see SSL certificate problem: unable to get local issuer certificate:

apt-get update && apt-get install ca-certificates   # Debian/Ubuntu
yum update ca-certificates                           # CentOS/RHEL

UPO Not Downloading (Stuck at SUBMITTED)

If a record has been SUBMITTED for 10–20 minutes (normal MF processing time is under 3 minutes):

Check MF server status: https://status.ksef.mf.gov.pl — if there is an active incident, wait for resolution
Check ksefpl.log for UPO polling errors — the module logs each polling attempt
If polling is failing with a network error, fix the connectivity issue and the module will resume polling automatically on the next cron run

If the MF session expired (>30 minutes) before UPO was retrieved, the session is lost. Mark the record as FAILED and re-submit.

Getting Support

When contacting plugkit.io support, include:

Audit log detail export: expand the failed record, click "Copy debug info" — this copies a JSON snapshot of the record
Log excerpt: var/logs/ksefpl.log entries for the affected time window (last 100 lines around the failure time)
PrestaShop version: Advanced Parameters → Information
PHP version: from the same page
KSeF environment (test or production)
Whether the issue is on every order or specific orders

Open a ticket at plugkit.io/support with all items attached.