MNB PHPExcelDeveloper Guide
v2.0.5
Documentation versions v2.0.5Current v2.0.4Maintenance v2.0.3Maintenance v2.0.0Initial v2 Compare versions →
Production guide

Troubleshooting Common Errors

Diagnose installation, package, workbook, password, memory, database, HTTP, and output problems.

Updated

LevelAll levelsReading time10 minPackageAny installed module

What you will learn

  • Use symptoms to identify the correct subsystem.
  • Collect useful diagnostics before opening an issue.
  • Avoid common output corruption and deployment mistakes.
Class “Mnb\PHPExcel\…” not found
Run composer install, include vendor/autoload.php, and confirm the intended package exists in composer show.
Composer still installs old code
Check composer show mnb/mnb-phpexcel, verify the new immutable tag exists on Packagist, then run composer update mnb/mnb-phpexcel -W.
XLSX is slow or consumes extra memory
Enable ext-zip and ext-xmlreader, use projection, avoid toArray(), and choose the large reader for huge files.
Wrong password or encrypted workbook error
Confirm the password exactly, avoid surrounding whitespace, check the encryption mode, and confirm the file is encrypted XLSX rather than legacy XLS.
PDO driver not found
Enable the correct driver such as pdo_mysql, pdo_pgsql, or pdo_sqlite and restart the PHP process.
Headers are not detected correctly
Use an explicit physical row, inspect detectHeader(), and require confirmation when confidence is low.
Worksheet selection throws an error
Call sheetNames() first, remember worksheet numbers are 1-based, use sheetIfExists() for optional values, or sheetOrActive() when null/empty input should use the active sheet.
Call to isEmpty() or rows() on array
toArray() and toStructuredSheetArray() return native arrays. Check $rows === [] or $data['rows'] === []; call isEmpty() before terminal conversion.
Row totals do not match returned data
Read $data['summary']['row_counts']. total includes sparse row-number gaps, source_records counts stored rows, skipped_empty counts removed explicit empty records, and returned is the final data count.
Generated file will not open
Run assertValidXlsx(), check that no HTML/whitespace was sent before a binary download, and verify the output path is writable.
A browser download is empty or corrupt
Clear output buffers, set XLSX content headers, send the exact file length, call readfile(), and exit immediately.
Queue jobs retry forever
Set maximum attempts, use idempotent unique keys, classify permanent validation errors separately, and move exhausted jobs to failed storage.
SMTP delivery fails
Verify DNS, port, STARTTLS/SMTPS mode, credentials, sender policy, CA certificates, and provider limits.