Most problems show up in two places: the Windows Event Viewer (Application and System logs) when the service does not start, and — once you can sign in — Settings › Application logs in the console. Start there.
The installer or the service does not start
| You see | Cause and fix |
|---|---|
| "Windows protected your PC" | SmartScreen, because the installer is not yet code-signed. Check the SHA-256 checksum, then More info › Run anyway. |
| The installer says the port is in use | Another program uses the port. Find it with Get-NetTCPConnection -LocalPort 8181, or choose another port in the installer. |
| The installer stops while copying files | An antivirus may hold the files. Run the installer again; if it repeats, add C:\phaf\app to the antivirus exclusions while installing. |
Unexpected token or JSON error after editing config.json | The file is invalid: a single backslash in a path or a missing comma or quote. Correct it as shown in Install and restart the service. |
EPERM or EACCES on C:\phaf\data | The service account cannot write to the data folder. Repeat the folder permissions. |
| The service is "Running" but nothing answers | Check the Event Viewer and that the port in config.json is the one you open. The service restarts phaf after a failure, so look for repeated errors. |
The console does not open
| You see | Cause and fix |
|---|---|
| It works on the server but not from other computers | Expected without a proxy: phaf only listens on 127.0.0.1. Set up HTTPS with IIS or nginx and open port 443. |
| IIS error 502.3 or "bad gateway" | phaf is not running, or the rule points to the wrong port. Check Invoke-WebRequest http://127.0.0.1:8181/ on the server. |
| IIS error 404.11 or 404.4 | allowDoubleEscaping is missing from web.config, or the proxy is not enabled in ARR. Repeat step 2. |
| Uploads fail with 413 or 404.13 | Raise maxAllowedContentLength (IIS) or client_max_body_size (nginx) to 64 MB. |
| Certificate warning in the browser | The certificate does not match the name in the address bar, or its authority is not trusted by users' computers. |
| Every user appears with the server's IP address | Set the proxy header to X-Forwarded-For in Settings › Security › Network access. |
Locked out
- "Account locked" — 5 wrong passwords or codes lock the account for 15 minutes. Wait, or ask another administrator to check the account.
- Blocked by IP rules — on the server, open
C:\phaf\data\profile.cfgwith Notepad as administrator and correct or empty theTrustedIPandBlockedIPlines in the[Application]section. The change applies immediately, without restarting. - Lost two-factor device — another administrator removes the user's 2FA in Settings › Users; the user sets it up again at the next sign-in.
- The only administrator forgot the password — contact support. To avoid this, keep two administrators.
Database problems
| You see | Cause and fix |
|---|---|
| Banner "the database is not available"; nothing is processed | phaf cannot reach the application database and retries every 30 seconds. The banner and Settings › Advanced › Database show the error. |
| Connection timeout to SQL Server | TCP/IP disabled, wrong port, firewall, or SQL Server Browser stopped for a named instance. Test from the phaf server: Test-NetConnection sql01 -Port 1433. |
| Login failed for user | Wrong user or password, the login is disabled, or the instance does not allow SQL Server authentication. |
| Password cannot be decrypted | The ENC:v1: value was created on another installation. Encrypt it again on this server (step 3). |
Certificate error with "trustServerCertificate": false | The SQL Server certificate does not match the name in server, or its authority is not trusted by the phaf server. Fix the certificate, or use true temporarily. |
| CREATE TABLE permission denied | The login is missing db_ddladmin in the phaf database. |
phaf runs but does not process
- Safe Mode banner — click Leave Safe Mode in Settings › Advanced, and remove
"safeMode": truefromconfig.jsonif it is there. - Disk usage banner — the data drive passed a threshold set in Settings › Alerts. Free space or enlarge the disk; processing resumes on its own.
- Network shares not reachable — a local service account cannot open domain shares. Run the phaf service with a domain account that has access.
- No email alerts — use Send test email in Settings › Alerts; it shows the SMTP conversation step by step.
Lost encryption key
If phaf.master_key is lost and there is no copy, phaf cannot read the passwords stored with it. Flows and settings remain, but you must enter again every connector and connection password and every certificate password, encrypt the database password again, and users must set up two-factor authentication again. Restore the key from your safe copy whenever possible.
Contact support
Open a support ticket with the phaf version, the Windows Server version, the database you use, the errors from the Event Viewer and the relevant lines from Settings › Application logs. Never send phaf.master_key, config.json passwords or the contents of the data folder.