Troubleshooting

This guide covers the most common issues with Fakturownia Pro for WooCommerce. Start every diagnosis by enabling debug logging, then follow the specific issue section.

Enable Debug Logging First

Before diagnosing any issue, enable debug logging to get detailed API and plugin traces:

1. Go to WooCommerce → Fakturownia Pro → Advanced
2. Enable "Debug Logging"
3. Reproduce the issue (trigger an order status change, or use the Regenerate button on the order)
4. Review logs at WooCommerce → Status → Logs — select fakturownia-pro from the dropdown

Via WP-CLI:

# Enable debug logging
wp option patch update fakturownia_pro_settings debug_logging true
 
# Get the log file path
wp eval 'echo WC_Log_Handler_File::get_log_file_path("fakturownia-pro");'
 
# Tail the log in real time
tail -f $(wp --quiet eval 'echo WC_Log_Handler_File::get_log_file_path("fakturownia-pro");')

Disable debug logging after investigation — logs contain invoice data.

API Connection Issues

"Invalid API token" Error

Symptoms: Red error banner after clicking "Save & Test Connection."

Diagnosis:

# Check what token is stored (first 20 chars only for security)
wp option get fakturownia_pro_settings --format=json | \
  python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('api_token','')[:20])"

Common causes and fixes:

1. Token missing subdomain: The full token format is AlphanumericString/yoursubdomain. Paste the complete string.
2. Subdomain field contains full URL: The Subdomain field should contain only yourcompany — not yourcompany.fakturownia.pl. Remove the .fakturownia.pl portion.
3. Trailing whitespace: Copy the token into a plain text editor first, then into the plugin. Many password managers add invisible trailing characters.
4. Fakturownia account inactive: Log in to Fakturownia.pl directly to verify your account is active and the plan is not expired.

"Connection timeout" Error

Symptoms: Test Connection hangs for 15+ seconds and returns a timeout.

Diagnosis:

# Test outbound connectivity from the server
curl -I https://app.fakturownia.pl

Expected: HTTP/2 200 or HTTP/2 405. Any other result indicates a network issue.

Fixes:

1. Outbound HTTPS blocked: Your hosting firewall may block outbound connections. Add app.fakturownia.pl to the allowlist, or contact your host to enable outbound HTTPS.
2. Proxy required: Some corporate hosting requires a proxy for outbound connections:

   // Add to wp-config.php:
   define('WP_PROXY_HOST', 'your.proxy.host');
   define('WP_PROXY_PORT', '8080');

3. Increase timeout: Go to Advanced → API Request Timeout and increase to 30 seconds.
4. DNS resolution failure: Test curl -v https://app.fakturownia.pl 2>&1 | head -20 — if DNS resolution fails, check your server's DNS configuration.

HPOS Migration Issues

Invoices Not Generating After HPOS Migration

Symptoms: Invoice rules stop firing after enabling HPOS in WooCommerce Settings → Advanced → Features.

Root cause: A conflicting plugin reads order data directly from wp_posts instead of using wc_get_order(), causing woocommerce_order_status_changed to fire inconsistently or with stale data.

Diagnosis:

# Verify HPOS is active
wp option get woocommerce_custom_orders_table_enabled
 
# Check Action Scheduler for pending Fakturownia jobs
wp action-scheduler list --hook=fakturownia_pro_generate_document --status=pending --format=table
 
# Check for compatibility mode (both storage methods active)
wp option get woocommerce_custom_orders_table_data_sync_enabled

Fixes:

1. Disable compatibility mode: In WooCommerce → Settings → Advanced → Features, ensure "Orders compatibility mode" is disabled. Compatibility mode runs both storage systems in parallel and can fire duplicate status change events.

2. Identify the conflicting plugin: Deactivate all plugins except WooCommerce and Fakturownia Pro. If invoices start generating, reactivate plugins one by one until the conflict is found.

3. Common offenders: Legacy order export plugins (version 1.x), some older payment gateways that directly update wp_posts, custom code using $wpdb->get_results to query orders.

"Order not found" in Meta Box After HPOS Migration

Symptoms: The Fakturownia Pro meta box in the order detail sidebar shows "Order not found."

Root cause: The HPOS migration has not completed, or there is a data sync gap between wp_posts and wc_orders.

Fix:

# Check HPOS migration status
wp wc hpos migration-status
 
# Complete the migration if incomplete
wp wc hpos enable --force
wp wc hpos migrate --batch-size=100
 
# Reindex Fakturownia Pro's internal order references
wp fakturownia reindex --confirm

WP-Cron Not Running

Symptoms

• Invoices are queued (order meta shows "Pending") but never generated
• Bulk generation starts but does not complete
• Retry queue items remain as "Pending" indefinitely

Diagnosis

# Check if WP-Cron is disabled
grep -i "DISABLE_WP_CRON" wp-config.php
 
# List scheduled Fakturownia cron events
wp cron event list | grep fakturownia
 
# Check Action Scheduler for stuck jobs
wp action-scheduler list \
  --hook=fakturownia_pro_process_queue \
  --status=pending \
  --format=table

Fixes

If DISABLE_WP_CRON is set to true, WP-Cron never fires automatically. Add a real system cron:

# Add to server crontab (crontab -e):
* * * * * php /var/www/html/wp-cron.php > /dev/null 2>&1

Or using WP-CLI:

* * * * * cd /var/www/html && wp cron event run --due-now --quiet >> /var/log/wp-cron.log 2>&1

If WP-Cron is enabled but events are not running:

# Test manual cron run
wp cron event run fakturownia_pro_process_queue
 
# If this runs without error, cron is working — the issue is scheduling
# If it errors, check WooCommerce Action Scheduler health:
wp action-scheduler run

Force-process the queue manually:

wp fakturownia process-queue --force

This runs the queue processing synchronously (blocking) and is useful for debugging whether the queue itself is functional.

Memory Limit Issues

Symptoms

• Bulk generation fails after processing some orders
• Error in logs: PHP Fatal error: Allowed memory size of X bytes exhausted
• Large invoices with many line items fail to generate

Diagnosis

# Check current PHP memory limit
wp eval 'echo ini_get("memory_limit");'
 
# Check peak memory during an invoice generation (add to wp-config.php temporarily)
# define('FAKTUROWNIA_DEBUG_MEMORY', true);

Fixes

# Increase memory limit in wp-config.php
define('WP_MEMORY_LIMIT', '256M');
define('WP_MAX_MEMORY_LIMIT', '512M');

Or in php.ini / .htaccess:

# .htaccess
php_value memory_limit 256M

# php.ini
memory_limit = 256M

For bulk generation specifically, the memory limit applies per batch. Reduce batch size if memory remains an issue:

# Reduce bulk batch size in wp-config.php
define('FAKTUROWNIA_BULK_BATCH_SIZE', 10);  // Default is 20

REST API Conflicts

Symptoms

• Other REST API plugins return unexpected responses when Fakturownia Pro is active
• Fakturownia Pro AJAX actions return 403 Forbidden

Root Cause

Security plugins (Wordfence, iThemes Security, WordFence) sometimes block outbound HTTP requests made by server-side PHP. Fakturownia Pro uses wp_remote_post() (WordPress's HTTP API) for Fakturownia API calls — this is not a REST API call from the client side, but some security rules flag it.

Fixes

Wordfence:

1. Go to Wordfence → Firewall → Advanced Firewall Options
2. Add app.fakturownia.pl to Whitelisted URLs

iThemes Security:

1. Go to Security → Settings → Site Check
2. Add app.fakturownia.pl to the outbound request allowlist

Generic firewall:

# Find Fakturownia's IP ranges (these may change — use hostname rules when possible)
nslookup app.fakturownia.pl
# Allow outbound HTTPS to the returned IP ranges

Invoice Not Attaching to Email

Symptoms: WooCommerce order confirmation or status email sent without invoice PDF attached.

Diagnosis checklist:

1. Is the invoice generated? Check the order meta box for an invoice number. If no invoice exists yet, the PDF cannot be attached.
2. Is "Attach PDF" enabled for the specific email type? Go to WooCommerce → Fakturownia Pro → Documents → Attach PDF to Email and verify the correct email type is checked.
3. Is the timing correct? The PDF is attached when the email is sent. If the invoice is generated after the email was already sent (because the invoice rule fires on a later status change), the attachment cannot be retroactively added.

Fix for timing mismatch: Add a "Send Email" action in your Invoice Rules for the status that generates the invoice. This sends a separate invoice email with the PDF after the invoice is created, even if the main order email was already sent.

Fix for hook priority conflict:

// If another plugin is interfering with email attachment hooks:
add_filter('fakturownia_pro_email_attachment_priority', fn() => 25);

Higher numbers run later — setting to 25 ensures Fakturownia Pro's hook runs after competing email plugins.

Invoice Created But Wrong Buyer Name/NIP

Symptoms: Invoice shows incorrect buyer information despite correct data in Shopify order.

Check the buyer data resolution order (see Configuration — Buyer Data Source):

1. Extension attribute fakturownia_nip: Is the NIP in order meta as _billing_nip? Check with wp post meta list ORDER_ID | grep nip
2. Customer tax_id: Is a conflicting tax_id stored on the customer billing address?
3. Billing fields: Are billing_company and billing_first_name/billing_last_name correct on the order?

Use the debug log to trace exactly which buyer data is being sent to the Fakturownia API — the payload is logged at debug level.

Getting Support

Collect these items before contacting support:

# System info
wp --info
wp plugin list --status=active --format=table | grep -E "woocommerce|fakturownia"
wp eval 'echo PHP_VERSION;'
 
# Plugin settings (redact API token before sending)
wp option get fakturownia_pro_settings --format=json
 
# Recent logs
wp eval 'echo WC_Log_Handler_File::get_log_file_path("fakturownia-pro");'
# Then: tail -n 100 [returned path]

Submit to support@plugkit.io with:

• WooCommerce System Status report (WooCommerce → Status → Get system report)
• The debug log excerpt
• The affected order ID(s)
• Description of the issue with steps to reproduce

Next Steps

• Changelog — check for recent bug fixes
• Configuration — review settings
• Invoice Rules — confirm rule configuration