Deutsche Version

Back to overview

LeaveFlow: Troubleshooting

Installation and configuration

The setup wizard cannot be submitted

Cause: At least one system check is red. Solution: Read the note next to the entry. Apply pending migrations with docker compose exec -u app app php bin/console doctrine:migrations:migrate --no-interaction. An unreachable database is usually caused by DATABASE_URL or by the database container not being ready yet. The writable directories must be var/ and public/uploads/.

Settings from .env.local have no effect

Cause: compose.yaml hard-sets DATABASE_URL and MAILER_DSN as container environment variables, and these take precedence. Solution: Change the values in compose.yaml (see Installation).

Slack token or LDAP bind password cannot be saved

Cause: APP_LDAP_ENCRYPTION_KEY is empty or not a valid 32-byte Base64 key. Solution: Generate and set a key (command on the Installation page). If you changed the key after values were stored, the LDAP login fails with a connection error and you must re-enter the bind password, Slack token and signing secret.

Signing in does not work over HTTP

Cause: The PHP configuration sets session cookies with the Secure flag. Solution: Run the instance behind HTTPS outside localhost.

Emails and scheduled tasks

No emails arrive

Check:

• In the Compose stack all mail goes to Mailpit (http://localhost:8025), because MAILER_DSN is smtp://mailer:1025.
• Outside APP_ENV=dev mail goes through the queue and needs the worker messenger:consume async.
• The sender no-reply@leaveflow.test is hard-coded, some SMTP servers reject it.
• Under notification Settings the recipient may have switched off email for the event.

Warnings, escalations and illness alerts do not appear

Cause: No Messenger worker runs for scheduler_notifications, or the job is disabled. Solution: Set up the worker (Operations) and check the status at /admin/scheduled-jobs. The escalation only applies to requests with status "Pending" and runs once per request.

The year transition did not happen

Cause: The worker scheduler_maintenance was not running on 1 January at 01:00. The scheduler does not catch up on missed ticks. Solution: Run app:entitlement:year-transition --year=<previous year> manually. The command skips entries that already exist.

Sign-in

"Sign in with Google" or "Sign in with Microsoft" is rejected

Possible causes:

• The email address already belongs to another account (for example a local one). Accounts are not merged automatically.
• The Google domain does not match the restriction, or the tenant ID does not match.
• The sign-in method is not enabled in the company settings.

After login it says "No employee profile is linked to your account"

Message: "No employee profile is linked to your account. Please contact your administrator." Cause: The user account is not linked to an employee. Solution: In the admin under Employees edit the record and select the account in the field "Linked user".

A user lost their 2FA device

Solution: They use a backup code. If none are left, an admin resets 2FA under Users with "Reset 2FA".

Leave requests

"No leave entitlement exists for yet."

Message: "No leave entitlement exists for yet. Please contact your administrator." Cause: The employee has no leave balance for the year. Solution: The admin creates an entry under Leave balances. The message only applies to absence types that deduct from the leave balance.

"Your leave balance is insufficient"

Message: "Your leave balance is insufficient: h requested, h available (including pending requests)." Cause: The requested hours exceed the available balance including the hours of pending requests, during probation only pro-rata earned hours count. Solution: Shorten the request or have the balance checked.

The request cannot be submitted: blackout period or backdated

Cause: The period overlaps a blackout period, or the start date is in the past. Solution: Choose another period. The admin handles corrections for the past.

A manager does not see a request

Check:

• Does the user account have at least the Manager role?
• Is the person entered under Departments as team lead or deputy of the requester's active department?
• Is the requester assigned to a department? Without one only admins decide.
• Nobody decides their own requests.

Nobody was notified about a new request

Cause: There is no active team lead or deputy who is not the requester. Admins see the requests in the approval list, the escalation reports them after the escalation threshold.

Integrations and API

Slack says "Dein Slack-Account ist nicht mit LeaveFlow verknüpft"

Cause: No Slack user ID is stored on the user. The interface offers no field for it, see Sign-in and integrations.

Slack commands answer with 503 or 403

Cause: 503 means the integration is not active or the signing secret is missing. 403 means the signature is invalid or the request is older than five minutes. Solution: Check the signing secret and compare the server time.

The API answers with 401

Cause: The token is invalid, revoked or expired, or the header does not use the Bearer scheme. Solution: Create a new token under API Access Tokens.

Known limitations

• One installation manages exactly one company.
• Holidays are only calculated for the 16 German federal states.
• The Slack user ID cannot be maintained in the interface.
• The sender of the system emails cannot be configured.
• Employees and users cannot be deleted, only exited and anonymized.
• Anonymization runs manually only.