﻿# Troubleshooting and FAQ

> Every page opens the licence page. The application has no valid licence (none, expired or corrupted). Upload a licence file; no sign-in is needed while there is no valid licence (Licence).

Source: https://workwise-solutions.net/docs/troubleshooting-faq/ · Language: en · Hungarian version: https://workwise-solutions.net/hu/docs/troubleshooting-faq/

## Where to look first

1. **Hiba Események** (Error events): errors returned to users, with request IDs ([Audit and logs](https://workwise-solutions.net/docs/features/audit-and-logs/)).
2. **Naplófájlok** (Log files), or the server logs: `docker logs -f worksmarthub`, `journalctl -t WorkSmartHub -f`, or the `Logs` folder.
3. **Státusz** (Status): version, database, user store, and your own permissions and groups.

## Installation and start-up

**Every page opens the licence page.** The application has no valid licence (none, expired or corrupted). Upload a licence file; no sign-in is needed while there is no valid licence ([Licence](https://workwise-solutions.net/docs/features/licence/)).

**`SECURITY:` warnings in the log at start.** A signing key still has the shipped value, or `PublicBaseUrl` is empty ([Configuration](https://workwise-solutions.net/docs/installation/configuration/#signing-keys)).

**`libsodium` error at start on Windows.** The Microsoft Visual C++ Redistributable (x64) is missing ([Windows (IIS)](https://workwise-solutions.net/docs/installation/windows-iis/)).

**The application does not start with Active Directory on Linux or in Docker.** Active Directory is Windows-only. Use LDAP, Entra ID or OAuth ([Authentication](https://workwise-solutions.net/docs/installation/authentication/)).

**The container is unreachable.** Set `HttpSettings__Urls__0=http://+:8080` with the container-side port of your `-p` mapping.

**`appsettings.json is read-only` in the log.** Information only: new settings of a newer release use their defaults until you add them to your file.

**Scheduled jobs did not run.** The process must run permanently. Under IIS check *Start Mode: AlwaysRunning*, *Idle Time-out: 0* and *Preload Enabled* ([Windows (IIS)](https://workwise-solutions.net/docs/installation/windows-iis/)). Job times are local server time (UTC in Docker).

## Signing in

**Signed out right after signing in, or the session is lost.** The sign-in cookie is sent only over HTTPS. Serve the site over HTTPS; do not turn `SecureCookie` off on deployed installations.

**Users must sign in again on another server.** All servers need the same `appsettings.json`, including the JWT signing key, and the same database.

**Forgot password e-mail does not arrive.** The page gives the same answer for known and unknown addresses, so it cannot tell whether an account exists. Check `EmailSettings` and the error events. Password reset is available for local and external users only.

**"Bad Request – Header field too long" with Active Directory.** The user is in many groups; raise the HTTP.sys header limits ([Windows (IIS)](https://workwise-solutions.net/docs/installation/windows-iis/)).

## Permissions and visibility

**A user does not see a menu item.** Check the user's application permissions and workspace roles ([Permissions and roles](https://workwise-solutions.net/docs/permissions-and-roles/)). Pages under *Alkalmazás* are hidden from users who have only *Public* unless enabled in **Oldal Láthatóságok**.

**A user does not see a ticket.** Technicians and readers see only tickets assigned to them or their groups. Check the ticket's *Munkát végző felhasználók/csoportok* and the user's groups (Status page, *Minden csoport*).

**A technician cannot change a field.** Technicians can change only the status, assignees, acting works, components and attachments; other fields are read-only.

**The client's details did not change after saving the ticket.** Only some users may change a client's details from a ticket; the ticket was saved, the client was not ([Permissions and roles](https://workwise-solutions.net/docs/permissions-and-roles/#client-details-changed-from-a-ticket)).

**The workspace selector shows "Nincs hozzáférése egyetlen munkaterülethez sem".** The user has no role in any workspace.

## Tickets

**Saving fails with a component quantity error.** There is not enough of a component in stock. Lower the quantity or increase the stock on **Komponensek**.

**"Munkajegy ezzel a névvel már létezik".** Ticket names are unique within a workspace.

**I cannot choose a delivery status.** *Kiszállításra vár*, *Kiszállítás alatt* and *Kiszállítva* need a delivery on the ticket.

**"Fájlok kiválasztása" is disabled.** Choose a file storage and save the ticket first.

**The "Késés értesítés küldése" button is disabled.** The ticket is in a closed status.

**Nobody received a notification.** The ticket has no notification channel, or the users have empty notification fields or opted out on their profile. Test the channel with **Teszt**.

**Client e-mails are not sent.** Client e-mails use `EmailSettings` in `appsettings.json`, not notification channels. Without a sender address (`FromEmail`) they are skipped; tickets are still saved. A send that fails is logged as a warning (*Failed to send … to client*) and the e-mail does not appear on **Ügyfél Email Események**; that list shows only e-mails that were sent.

## Files and uploads

**Upload fails with 413 Request Entity Too Large.** A reverse proxy refused the body. Allow at least the chunk size (25 MB by default): `client_max_body_size 50m;` in nginx, the ingress body size annotation in Kubernetes.

**A component image cannot be uploaded.** Only PNG and JPEG are accepted, and only into an application-level file storage.

**A file storage test fails after editing.** Enter the secret again: testing an edited storage needs it ([File storages](https://workwise-solutions.net/docs/features/file-storages/)).

**Attachment links stopped working after moving the server.** Links are rebuilt for the current host on each request; if they still fail, the link signing key changed. Keep the same keys when moving.

## E-mail channels

**The SMTP test fails with SSL on.** The server must offer STARTTLS with a trusted certificate that matches the host name. Port 465 (implicit TLS) is not supported; use 587.

**A save is refused after changing the SMTP host.** Enter the password again in the same save: changing where a secret is sent requires it.

## Invoices

**Conversion to final invoice is refused "try again shortly".** A payment is being recorded at Számlázz.hu; wait 2 minutes. After a failed payment recording, use **Fizetés rögzítése újra** first.

**A warning says the Számlázz.hu account may have changed.** A document found at Számlázz.hu did not match the invoice. Check that the API key belongs to the right account ([Invoices](https://workwise-solutions.net/docs/features/invoices-szamlazz-hu/)).

**An invoice was not issued automatically.** Automatic invoicing runs only when a ticket admin (not a technician) changes the status to *Számlázandó*, only if the ticket has no invoice that is not cancelled (a failed one counts), and only while invoicing is enabled. The reason of a refused attempt is on **Hiba Események** and in the log.

**Számla kiállítása is disabled on a ticket.** The checklist in the ticket's invoices dialog shows the missing item in red: the API key, the company details, the invoice prefix, the client's name, address and city, or invoiceable items. Fill in what is missing and open the dialog again.

![Checklist with a missing item](https://workwise-solutions.net/docs/images/szamlazz-ticket-checklist-missing.png)
*Ügyfél neve, címe és városa megadva is red: the client has no city.*

**The configuration check fails.** *Sikertelen bejelentkezés. Ellenőrizze az API kulcsot.* means Számlázz.hu refused the stored key: enter the agent key of the right account again. *Nem sikerült csatlakozni a Számlázz.hu-hoz.* means the server cannot reach Számlázz.hu.

**The preview refuses the VAT treatment.** The client does not fit the chosen treatment, for example an intra-EU treatment for a Hungarian client, or domestic reverse charge for a client without a Hungarian tax number. Correct the client's country, EU VAT number or tax number, or choose another treatment.

![Refused VAT treatment](https://workwise-solutions.net/docs/images/szamlazz-error-treatment.png)
*A Közösségen belüli szolgáltatás áfakezelés csak másik EU-tagállambeli ügyfélnek választható, az ügyfél magyarországi.*

**An invoice in EUR or USD is refused without a rate.** An invoice in another currency than the price currency needs the rate your company uses for the fulfilment date. Type it in the *Árfolyam* field.

![Missing exchange rate](https://workwise-solutions.net/docs/images/szamlazz-error-rate.png)
*A HUF árakból EUR számla csak árfolyammal készülhet: the Árfolyam field is required.*

**A correction asks for the rate.** The EUR or USD invoice stored no rate. Type the rate printed on the original invoice; the correction cannot be issued without it.

![Rate asked by the correction](https://workwise-solutions.net/docs/images/szamlazz-correction-rate.png)
*Az E-UCFXX-2026-127 számla EUR pénznemű, és nincs eltárolva az árfolyama.*

**Számlázz.hu refused the invoice.** The invoice is stored as *Sikertelen*, and its row shows Számlázz.hu's error code and message. Correct the cause, delete the failed invoice and issue it again. In the example the invoice prefix in the settings does not exist in the Számlázz.hu account.

![Invoice refused by Számlázz.hu](https://workwise-solutions.net/docs/images/szamlazz-error-refused.png)
*202: Ez a számlaszám előtag nem létezik vagy nincs engedélyezve.*

**Számlázz.hu gave no answer.** The invoice shows *A Számlázz.hu nem adott értékelhető választ a számla kiállítására*, and the outcome is unknown. For 5 minutes a new attempt is refused (*Az előző számla kiállítására a Számlázz.hu nem adott értékelhető választ, és néhány percig még elkészülhet.*). After that, a retry first looks the document up at Számlázz.hu and stores it if it exists; the status sync job does the same on its next run. You do not need to check Számlázz.hu by hand.

![New attempt refused](https://workwise-solutions.net/docs/images/szamlazz-unknown-refusal.png)
*Az előző számla kiállítására a Számlázz.hu nem adott értékelhető választ, és néhány percig még elkészülhet.*

**A correction is not issued.** Before a correction WorkSmartHub refreshes the invoice's payment state from Számlázz.hu. If Számlázz.hu does not answer, the message ends with *A helyesbítő számla nem készült el; néhány perc múlva próbálja újra.* If Számlázz.hu has another document under the number, check the API key.

**A second invoice is refused.** *A munkalaphoz már tartozik ilyen típusú érvényes vagy kiállítás alatt álló bizonylat.* The ticket already has an open document of that type, or another user issued it at the same moment. *A munkalapra az elmúlt 5 percben már készült bizonylat* means a document was issued on the ticket in the last 5 minutes. Refresh the page and check the ticket's invoices.

**The VAT rate or the currency is refused at save.** While invoicing is on, the VAT rate must be 27, 18, 5 or 0, and the price currency HUF, EUR or USD ([Invoices](https://workwise-solutions.net/docs/features/invoices-szamlazz-hu/#setting-it-up)).

## FAQ

**Can I use WorkSmartHub on a phone?** The web portal is designed for desktop screens. Use the mobile app, activated with the QR code under **Mobil Alkalmazás** ([Mobile app](https://workwise-solutions.net/docs/features/mobile-app/)).

**Can I edit the e-mail texts?** Yes, by editing the template files on the server ([Notifications](https://workwise-solutions.net/docs/features/notifications/#templates)).

**Can the interface be shown in English?** No, the interface is in Hungarian.

**Does deleting a client delete its tickets?** Yes. Mark clients as *Inaktív* instead.

**Does deleting a ticket give back the components?** Yes, all components of a deleted ticket return to stock.

**How do I see who changed a ticket?** On **Események** (Events), filtered by type and user. The ticket list's tooltips show who created and last modified each ticket.

**Can several teams share one installation without seeing each other's work?** Yes, that is what workspaces are for ([Workspaces](https://workwise-solutions.net/docs/features/workspaces/)).
