Audience: end users, admins, support engineers
Difficulty: new user
What this covers
The user-visible error messages Solavel and Solabooks can show,
why each one happens, and the most direct fix. Use this page to convert
a user complaint ("I can't load the invoice") into a single concrete
next step.
For the controller and middleware that emit each error, see the file
hints in the right column.
Authentication & access
| Error message |
Likely cause |
Fix |
| "No organization found." |
The user is signed in but has no membership row in user_organizations. Common after a stalled signup. |
Admin: open /admin/clients > the user's client > Members, and add the user. Or have the owner re-invite via /portal/orgs/{org}/members. |
| "Workspace not enabled." |
The user's organization has not completed workspace onboarding. The EnsureWorkspaceOnboardingCompleted middleware redirects all /portal/* and /client/* traffic. |
Open /onboarding/verify and complete the verification steps. Owner role required. |
| "Permission denied." |
A perm: or Spatie permission: middleware blocked the route, or a controller authorize() call failed. |
Verify the user's role: parent app (super-admin/admin/client_owner/client_manager/client_member); finance (owner/manager/member/approver). See admin-support/access-troubleshooting. |
| "Tenant not found." |
The finance app could not resolve a tenant database from the SSO context. Either the parent app didn't bootstrap the tenant, or the per-tenant credentials in services.tenancy derive a missing DB name. |
Run php artisan superadmin:setup --client-id=<id> on the finance app, or re-issue the SSO handoff from /sso/finance/redirect. |
| "Setup link is invalid or expired." |
A customer-portal account-setup token was already used, or it is older than 60 minutes. |
Customer should request a fresh link from the original document email. |
| "Reset link is invalid or expired." |
Password reset token > 60 minutes old or already used. |
Resend from /customer-portal/forgot-password. |
| "Customer portal login failed." |
Wrong password, or the customer portal account is not enabled, or the customer record is archived. |
Check customer_portal_accounts for that customer; ensure is_active = true. The customer can use Forgot Password at /customer-portal/forgot-password. |
Plan & feature gates
| Error message |
Likely cause |
Fix |
| "Plan does not include feature." |
A feature:<flag> middleware fired and the org's resolved value for the flag is false. Most common when a Free plan org tries to use a paid feature (Sales Orders, Mileage, Budgets, Fixed Assets, Recurring, Workflow Rules). |
Upgrade the plan via Portal > Billing, or have admin toggle the flag on the org for trial use. See admin-support/plan-feature-debugging. |
| "Feature is disabled for this organization." |
The feature is plan-eligible but the org-level toggle in Settings > Features is off. |
Owner toggles it on (Settings > Features). |
| "Inventory not enabled." |
inventory_enabled flag is off for this org. |
Settings > Features > Inventory. |
| "VAT not enabled." |
vat_enabled flag is off. Hides all tax/VAT routes. |
Settings > Taxes > Enable VAT (owner only). |
Document & posting
| Error message |
Likely cause |
Fix |
| "Invoice cannot be edited because it is posted." |
Editing a posted document is blocked by InvoicePolicy::update. |
Use Unpost if sales.invoices.unpost is granted, or Reverse and create a new invoice. |
| "Invoice cannot be edited because the period is locked." |
The document's date falls in a locked or closed period. |
Either use a date inside an open period, or have an owner unlock the period (periods.unlock). |
| "Period locked." |
A new posting is dated on or before the lock date. |
Adjust the document date forward, or move the lock date forward in Settings > Periods. |
| "Required account missing." |
A default account (AR, AP, Sales Revenue, Bank, etc.) is not configured. The system can't post without it. |
Open Setup Wizard or Settings > Accounting Defaults and pick the account. See accounting-rules. |
| "Payment cannot be recorded." |
One of: the customer has no open invoice; the bank account is missing or inactive; the payment date is in a locked period; the amount is zero or negative; the org's currency mismatches the bank account's currency. |
Check the customer's open invoices, the chosen bank account's status, and the document date. |
| "Document/customer mismatch for this portal link." |
A customer-portal link was issued for a document that has since been re-customer-assigned, or the link's customer differs from the document's. |
Re-issue the link from the document page (Send to Customer). |
| "This portal link is no longer active." |
Token is past its 24-hour expiry, or the link was revoked. |
Customer clicks Request access on the expiry page; staff resends from the document. See customer-portal/secure-document-links. |
| "Document link expired." |
Same as above (alternative wording for the same condition). |
Same. |
Reports
| Error message |
Likely cause |
Fix |
| "Report total mismatch." / "Trial balance does not balance." |
Out-of-balance posted journals (rare — system blocks at post), or a partial period close that left orphan retained-earnings movement. |
Open Reports > General Ledger, run on the same date range, look for journals with no offset. Escalate to support with the journal IDs. |
| "Report data is unavailable for this period." |
The filter range falls outside any fiscal year, or VAT period not generated for the range. |
Set up a fiscal year that covers the range, or generate periods in Settings > Periods. |
| "You are not allowed to export." |
reports.export permission missing. |
Owner grants reports.export to the role. |
Workspace control & SSO
| Error message |
Likely cause |
Fix |
| "SSO token expired." |
The signed token from sso.finance.redirect is older than its TTL. |
Click Sign in to Solabooks again from the parent portal. |
| "Workspace control: organization not found." |
The finance app called api/workspace-control/orgs/{id} with an org id the parent does not have. |
Confirm the org exists at /admin/organizations on the parent app. Re-run superadmin:setup if the tenant DB is fresh. |
| "Tap webhook signature mismatch." (admin only) |
Tap payment webhook came in with a wrong signature. |
Confirm services.tap.secret matches the Tap dashboard webhook secret. |
Background jobs and provisioning
| Error message |
Likely cause |
Fix |
| "Provisioning is still in progress." |
The finance tenant DB is being created in the background. The /finance/provisioning/status endpoint is being polled. |
Wait 30-60 seconds. If it persists past 5 minutes, run php artisan superadmin:setup --client-id=<id> on the finance app to bootstrap manually. |
| "Subscription not active." |
The user has no row in client_subscriptions with status='active' for the project they're trying to launch. |
Confirm the subscription in /admin/clients > [client] > Subscription. Resync if the upstream payment processor reported success but the local row didn't update. |
| "Workspace handoff failed." |
The cross-app token used to bootstrap the tenant connection is invalid. |
Restart the launch from the parent app (do not refresh the finance page). |
| "Sync signature mismatch." |
An ingest endpoint received a payload whose HMAC signature does not match. Either services.tenancy.shared_secret differs between apps, or the request was tampered with. |
Confirm both apps share the same secret. Re-run the sync from the parent admin. |
VAT and period
| Error message |
Likely cause |
Fix |
| "VAT period not generated." |
The fiscal year exists but VAT periods have not been generated in Settings > Periods. |
Click Generate Periods for the affected year. |
| "VAT return already settled." |
Trying to edit or finalize a VAT return that's already in settled state. |
Settled returns are immutable. Issue an adjustment in the next period. |
| "VAT return cannot be finalized — open transactions exist." |
One or more transactions in the period have status draft. |
Post or delete the draft transactions, then retry. |
| "Reverse charge not enabled." |
A line marked reverse-charge but reverse_charge_enabled is off. |
Enable the feature at Settings > Features > Reverse Charge. |
Customer portal — customer-facing wording
These are what a customer (not internal user) might see:
| Customer sees |
Meaning |
What customer should do |
| "This link has expired." |
24-hour token elapsed. |
Click Request access on the page. |
| "We sent a fresh link to your email." |
Sender side — send-again succeeded. |
Check email. |
| "Account setup link expired." |
Setup token > 60 min. |
Use the Forgot password flow at /customer-portal/forgot-password. |
| "Sign-in failed." |
Wrong password or disabled account. |
Use Forgot password. |
| "Your account is not active." |
customer_portal_accounts.is_active = false. |
Contact the company that issued the document. |
Related
