> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Post-upgrade troubleshooting

> Common issues and solutions that may occur after upgrading from FlowX v4.7.x to v5.1.0.

This section covers common issues that may occur after completing the upgrade to FlowX.AI 5.1.0 and their solutions.

## Designer login issues

### DataIntegrityViolationException error

If you cannot login to FlowX Designer after the 5.x upgrade and encounter the following error in the authorization-system logs:

```
org.springframework.dao.DataIntegrityViolationException: could not execute statement [ERROR: duplicate key value violates unique constraint "cas_user_username_key"
  Detail: Key (username)=(admin@flowx.ai) already exists.] [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; SQL [insert into public.cas_user (created_by,created_date,email,first_name,issuer,last_name,modified_by,modified_date,subject_id,username,id) values (?,?,?,?,?,?,?,?,?,?,?)]; constraint [cas_user_username_key]
```

**Root Cause**: This error occurs because the `sub` (subject ID) is missing from JWT tokens. Starting with Keycloak version 25, the `sub` claim is not added by default to lightweight access tokens.

**Solution**: Ensure the `basic` Client Scope is created in your Keycloak Realm and added to all FlowX clients.

<Warning>
  Since Keycloak version 25, the `sub` claim is not added by default to JWT lightweight tokens. This is a breaking change that affects FlowX.AI authentication.
</Warning>

### How to verify if subject ID is missing

<Steps>
  <Step title="Login attempt">
    Try to login to FlowX Designer and note if the login fails.
  </Step>

  <Step title="Capture the token">
    1. Open your browser's Developer Tools
    2. Navigate to the **Network** tab
    3. Attempt to login again
    4. Look for a call to: `https://<your-keycloak-address>/auth/realms/flowx/protocol/openid-connect/token`
    5. Copy the access token from the response
  </Step>

  <Step title="Decode the token">
    1. Go to [https://jwt.io/](https://jwt.io/)
    2. Paste the token in the **Encoded** section
    3. Check the **Payload** section for the presence of the `sub` claim

    <Check>
      If the `sub` claim is present, the token should contain a field like: `"sub": "12345678-1234-1234-1234-123456789abc"`
    </Check>
  </Step>

  <Step title="Verify Client Scope configuration">
    If the `sub` claim is missing, you need to configure the Client Scope in Keycloak:

    1. Login to your Keycloak Admin Console
    2. Navigate to your FlowX realm
    3. Go to **Client Scopes**
    4. Ensure the `basic` client scope exists and includes the `sub` claim
    5. Add this client scope to all FlowX clients (FlowX Designer, Admin, etc.)
  </Step>
</Steps>

### Additional resources

<Card title="Keycloak Release Notes" href="https://www.keycloak.org/docs/latest/release_notes/#lightweight-access-token-to-be-even-more-lightweight" icon="external-link">
  Official Keycloak documentation about lightweight access token changes
</Card>

***

## Other common issues

<Info>
  Additional troubleshooting sections will be added as common post-upgrade issues are identified. If you encounter issues not covered here, please consult the FlowX support team.
</Info>