Troubleshoot database integrations

Resolve gateway setup issues, integration creation issues, and end-user access issues.

For issues on an integration that's already running, check its health status first. See Database integration health status.

Gateway issues

What you're seeing	Likely cause	What to do
The gateway doesn't appear in Okta Privileged Access after setup.	The gateway service isn't running, or it failed to enroll.	Confirm that the service is running with sudo systemctl status sft-gatewayd. If it's running, check for enrollment errors with sudo journalctl -u sft-gatewayd. Restarting the service is safe, because gateways that service database integrations don't carry user sessions.
The gateway service doesn't start on amazonlinux 2023.	The required session log directory may be missing.	Run the following command: echo "SessionLogTempStorageDirectory: /var/log/sft/sessions/tmp" | sudo tee -a /etc/sft/sft-gatewayd.yaml sudo mkdir -p /var/log/sft/sessions/tmp

Integration creation issues

What you're seeing	Likely cause	What to do
A timeout error when creating the integration, and the gateway never picked up the request.	No gateway in the orchestration group could take the request.	Confirm that the gateway service is running, and that it's enrolled using a setup token configured for infrastructure orchestration. Confirm that the orchestration group in the integration matches the gateway.
A timeout error when creating the integration, and the gateway picked up the request.	The gateway couldn't complete the request within the allotted time, because the database instance didn't respond.	Ensure that there's connectivity from the gateway to the database instance on the port that the database listens on, and that the instance is running and accepting connections. See Network access by environment.
"The integration user doesn't have all the required permissions" when creating the integration.	The integration user is missing one or more privileges.	Ensure that the integration user has the privileges required for your database type. The error doesn't always name the privilege that's missing. See Database integration user privileges.
"Network error" or "Can't reach host" when creating the integration.	The gateway can't connect to the database instance.	Ensure that there's connectivity from the gateway to the database instance on the port that the database listens on. See Network access by environment.
"Can't integrate a read-only instance" when creating the integration.	The integration points to a read-only database instance.	Point the integration to the primary, write-enabled database instance.
"Operation was canceled" when creating the integration.	The request was canceled before it finished.	Select Test and Save integration again.
An error that names the integration user's credentials when creating the integration.	The username or password entered for the integration user is incorrect.	Confirm the username and password for the integration user, then try again. See Database integration user privileges.
A database version error when creating the integration. The error names the minimum-supported version and the version that the instance runs.	The database instance runs a version below the minimum that Okta Privileged Access supports.	Upgrade the instance to a supported version. See Supported database types, versions, and deployment options.
No accounts appear after you define the account rules.	The account rule doesn't match any database users, or the first discovery hasn't finished.	Onboarded accounts appear under Resource Administration > Integrations > integration name > Accounts. If none appears there, review the Operator and Value in the account rule. Saving the rule starts discovery and onboarding again. See Add an integration.
An integration to the same database target exists.	Okta Privileged Access allows only one integration for each database target.	Check the error message to identify the integration that conflicts. Use that integration, create an integration for a different database target, or contact Okta Support.

End user issues

What you're seeing	Likely cause	What to do
End users see no databases in their dashboard.	No published security policy covers their group.	End users see their databases under My Privileged Access > Databases. Create and publish a security policy that includes the user group.
End users can see databases but can't check out.	Checkout is disabled in project settings.	Enable checkout in the project settings. See Database accounts.