Skip to main content

Troubleshooting

Selecting a parent does not filter the ledger​

Inspect the request for a numeric parentId. A stale backend can ignore this new parameter and return every invoice. Restart/redeploy Spring with the matching controller/service/repository revision, then compare a filtered GET result with the selected parent's ID.

The frontend emits parent selections immediately and resets to page zero. It uses a primitive ID through the shared dropdown's valueKey mode.

Flyway V3 cannot change SUBJECT_ID​

The original subject column and referenced subject ID use INT(14). A change to BIGINT conflicts with the existing foreign key. The corrected V3 keeps the existing type and changes only nullability.

MariaDB may retain earlier DDL after a failure. Inspect Flyway history and the schema first: the unique parent/month index may already exist. The corrected migration tolerates that index. Repair only the reviewed failed migration; do not drop invoice data or disable foreign-key checks to force startup.

Batch calls return 403​

Compare runtime PRINT_WORKER_TOKEN values in Spring and Laravel. Spring sends X-Print-Worker-Token. A successful health check does not verify this protected integration.

PDF generation returns 404​

Check the HTTP method and path. Single invoice generation is POST /generate/invoice/{filename} with no /api prefix. Verify that the frontend's filerUrl points to the Laravel print service and that rewrite rules reach its entry point.

PDF layout differs from the old filer​

Check all three inputs separately: the Spring-selected DOCX filename, the rendered DOCX content, and the PDF conversion driver. The Google import/export path preserves the existing layout better than the converter used during the earlier Gotenberg comparison.

Do not assume a template is wrong when a different conversion engine clipped it.

FTP works in FileZilla but fails in PHP​

Check the full FTP username, host, port, SSL/passive settings, and remote root. The hosting account's full FTP login can differ from its short account name. Confirm the PHP FTP extension is available to the web runtime, not just CLI PHP.

Health works but PDFs fail on cPanel​

Check ZIP, DOM, fileinfo, iconv, database, and FTP extensions in web PHP. CLI and LiteSpeed PHP can load different configurations. The current account uses Alt-PHP 8.3 and an account-local extension selection.

Only index.php is visible in printing-service​

This is expected. Public files live in public_html/printing-service; the app is in .apps/tuition-print/current, and persistent credentials/data are under .apps/tuition-print/shared. Enable hidden-file display in File Manager to see .apps.

A delivery is marked needs_review​

The provider may have accepted the send before acknowledgement was lost. Inspect its records and the batch's review entries. Mark it sent, or explicitly authorize retry. Do not blindly resend all invoices.

Dashboard is empty​

Confirm the selected billing month and that invoices/payments have been saved. Forecasts use recorded history; a blank history produces zero estimates. The frontend no longer falls back to fabricated Fuse demo values.