3 min read 767 words Updated Jun 08, 2026 Created Jun 08, 2026

Troubleshooting

A collection of common issues and how to fix them. If you're not finding what you need here, check the logs on your Permiso instance (LOG_LEVEL=debug will give you more detail) or reach out to support.

Symptom: You generate a sign-up link and the email never arrives.

What to check:

  1. Go to Settings → Administration → Application Configuration → Email and verify your SMTP settings are saved correctly
  2. Make sure the From Address is a valid sending address that your SMTP provider allows
  3. If you're using Amazon SES, confirm the sending address is verified in the SES console
  4. Check your mail server's logs or dashboard for rejected or bounced messages
  5. Make sure the Permiso server can reach your SMTP host on the configured port; firewall rules often block port 587 outbound

Users can't register a passkey

Symptom: A user follows the sign-up link but gets an error when trying to register their passkey.

What to check:

  1. Passkeys require a secure context: the site must be served over HTTPS. If you're self-hosting, make sure your reverse proxy has TLS configured.
  2. The APP_URL environment variable must match the URL the user is accessing. Passkey registration is tied to the origin.
  3. The user's browser must support WebAuthn. Chrome, Safari, Firefox, and Edge all support it in recent versions.
  4. If the user is on a managed device with security policies, those policies may block WebAuthn. Check with your IT team.

SSO login fails with "redirect_uri_mismatch"

Symptom: A user tries to log into an application through Permiso and gets an error about the redirect URI not matching.

What to check:

  1. Open the OIDC client in Settings → Administration → OIDC Clients and check the Callback URLs
  2. The redirect URI your application is sending must exactly match one of the registered URLs, including the protocol (https://), domain, path, and no trailing slash vs. trailing slash
  3. Copy the exact redirect URI from your application's SSO settings and paste it as a new callback URL in Permiso

SSO login fails with "access_denied"

Symptom: The user authenticates successfully with their passkey but is denied access to the application.

What to check:

  1. Open the OIDC client and check whether Restrict to user groups is enabled
  2. If it is, make sure the user is a member of one of the allowed groups
  3. Also check that the user's account is not disabled

A user is locked out (lost their passkey)

Symptom: A user got a new device, or accidentally removed their passkey, and can no longer log in.

What to do:

  1. Go to Settings → Administration → Users and find the user
  2. Click Send login link to send them a one-time email link
  3. They follow the link to log in, then immediately register a new passkey from Settings → Account → Security

LDAP users can't log in

Symptom: Users that exist in the LDAP directory get an error when trying to log in.

What to check:

  1. Go to Settings → Administration → Application Configuration → LDAP and verify the connection settings
  2. Make sure the Permiso server can reach the LDAP server on the configured port
  3. Check that the bind DN and password are correct. A simple test is to verify them with an LDAP tool like ldapsearch
  4. Confirm the base DN is set broadly enough to include the users you're trying to sync
  5. Check the user and group search filters. An incorrect filter can prevent users from being found

Emails are sending but going to spam

Symptom: Invitation emails arrive, but land in users' spam folders.

What to check:

  1. Make sure your From Address is a real address on a domain you control
  2. Set up SPF, DKIM, and DMARC records for your sending domain. Most email providers have guides for this
  3. If you're using a shared SMTP service, check whether the shared IP has a poor reputation

The setup page isn't available

Symptom: You navigate to /setup but get a 404 or are redirected away.

What to check:
The /setup page closes permanently after the first admin account is created. If an admin account already exists, the page is gone. If you need to reset your instance, you'll need to clear the database and start fresh, or add a new admin from an existing admin account by going to Settings → Administration → Users and promoting a user to admin.