Docs / FAQ & Troubleshooting

FAQ & Troubleshooting

This page collects the most common operational, configuration, and access issues seen in Vendventory. Use it when a screen fails to load, a permission seems wrong, a report looks suspicious, mail does not send, or a user cannot complete an expected workflow.

Troubleshooting rule: identify the failure category first. Access failures, data failures, configuration failures, and integration failures often look similar at the surface but need different fixes.

Installation and Environment

Why is the app blank or failing right after install?

Check PHP version, required extensions, and writable directories against Requirements.
Confirm the database connection and migrations completed successfully.
Verify the application key exists and the environment file is readable.
Clear config, route, and view caches after environment changes.

How do I remove demo data without reinstalling?

Use Settings > Tools > Refresh Database.
Type the exact confirmation phrase REFRESH DATABASE when prompted.
The tool clears catalog, transaction, and shipped demo-account data while preserving system settings and the currently signed-in account.
It does not reinstall the application and it does not reseed demo data automatically.

Authentication and 2FA

A user cannot log in or keeps hitting OTP issues

Check whether the account is locked, suspended, banned, or awaiting verification.
Review login attempt limits and lock minutes in Settings.
Confirm mail or SMS delivery before assuming the OTP service is broken.
Verify the TOTP issuer and device clock when app-based codes fail.

Why is a password change request still pending?

Profile-submitted password requests require admin approval before a reset link is sent.
Check the admin password-request queue and confirm an authorized reviewer approved or rejected the request.
Remember that guest forgot-password remains direct and is not blocked by the approval workflow.
If the request was rejected, review the admin note and submit a new request only after the issue is resolved.

Permissions

Why does a page return 403 for one user but not another?

Confirm the exact permission string required by that route.
Check whether the user role was updated but cached permissions were not refreshed.
Review whether the user has the correct role and guard context.
For dashboard and report screens, remember that route access and action buttons may require different permissions.

Inventory Operations

Stock quantities do not match expectations

Check whether the transaction is still draft instead of completed.
Review stock-out reasons and stock-adjustment status carefully.
Inspect purchase completion state before expecting stock to rise.
Open related movement and drilldown reports to confirm how the balance evolved.

Why can I not edit or delete a stock-out or stock-adjustment?

Only draft records are editable or deletable.
Completed and cancelled inventory records are locked for audit and reporting integrity.
If you need a different result, create a new corrective document instead of trying to reopen a locked record.
Use the details drawer, movement reports, and reference numbers to understand what already posted.

Why does an archived product still appear in old documents or reports?

Archived products are removed from new transaction selectors, not from history.
Vendventory keeps archived products visible in historical purchases, stock-outs, stock-adjustments, product drawers, and reports so past numbers stay accurate.
Look for the Archived label to distinguish retired catalog items from currently active products.
Use force delete only when you intentionally want to purge the archived product and its linked history from analytics.

How do I permanently remove an archived product?

Open the archived product view from the Products module instead of the normal active list.
Use the archive-only Force Delete action.
Type the exact confirmation phrase FORCE DELETE when prompted.
Remember that force delete is destructive: it purges the product and its linked history, so reports and historical totals will change afterwards.

Reports and Exports

A report loads but the numbers look wrong

Check the current filters, date window, and sort options first.
Confirm the underlying purchases, stock-outs, or adjustments are completed and not draft.
Review master data quality for categories, suppliers, and products.
Compare the report to the dashboard and drilldown screens instead of relying on one view only.

Export files fail or do not download

Confirm the user has both the report access permission and export reports where required.
Verify that the export format is supported by the route.
Check server storage and temporary file permissions for PDF/XLSX generation.
If the report has no rows, confirm the export builder handles empty data gracefully.

Mail and Channels

Emails are not sending

Verify SMTP host, port, username, password, and encryption.
Confirm the sender address is valid for the provider.
Run the SMTP verification steps from SMTP Setup.
Check whether the server can reach the mail host from its network.

Copilot and AI Runtime

Copilot is visible but answers are limited or unavailable

Check whether AI is enabled and the provider key is present.
Use the AI status and connection test in Settings.
Remember that Vendventory may intentionally fall back to analytics-only behavior when AI credentials are unavailable.
Confirm the user also has the correct page permission for the requested analytics context.

Testing and Validation

What should I run after a risky change?

Run the targeted test file for the changed module first.
Run the broad admin module coverage suite if routes, permissions, or views changed.
Run report tests if dashboard or analytics builders changed.
Run the full feature suite before merge or deployment.

Support Checklist

Include these details in any support request

Exact page or route name.
User role and whether the issue affects all users or one user.
Absolute time and date of the issue.
Any visible error message, stack trace, or server log line.
Whether the issue also happens after cache clear and fresh login.
Screenshots only after masking secrets, keys, and personal data.

Do not send secrets: never include API keys, SMTP passwords, Twilio tokens, or raw recovery codes in tickets.