Troubleshooting SQL API — Connection, Authentication, and Query Errors<!-- /*NS Branding Styles*/ --> .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } body { font-family: Arial, sans-serif; font-size: 14px; color: #1d1d1d; max-width: 960px; margin: 40px auto; padding: 0 24px; line-height: 1.6; } p { margin: 10px 0; } ul, ol { margin: 8px 0 8px 24px; } li { margin-bottom: 4px; } table { border-collapse: collapse; width: 100%; margin: 16px 0; font-size: 13px; } th { background-color: #f0f0f0; text-align: left; padding: 8px 10px; border: 1px solid #ccc; } td { padding: 7px 10px; border: 1px solid #ccc; vertical-align: top; } tr:nth-child(even) { background-color: #fafafa; } .warning { background-color: #fff8e1; border-left: 4px solid #f5a623; padding: 10px 14px; margin: 16px 0; border-radius: 2px; } .warning strong { color: #b36200; } .note { background-color: #f5f5f5; border-left: 4px solid #999; padding: 10px 14px; margin: 10px 0; font-size: 13px; border-radius: 2px; } .result { background-color: #f0f7f0; border-left: 4px solid #4caf50; padding: 10px 14px; margin: 16px 0; border-radius: 2px; } .error-block { background-color: #f9f9f9; border: 1px solid #ddd; border-radius: 3px; padding: 8px 12px; font-family: monospace; font-size: 12px; color: #333; margin: 6px 0; white-space: pre-wrap; } .error-heading { font-size: 14px; font-weight: bold; background-color: #f4f4f4; border-left: 3px solid #aaa; padding: 5px 10px; margin-top: 20px; margin-bottom: 6px; display: block; } .faq-item { padding-top: 10px; margin-top: 10px; font-size: 14px; } hr { border: none; border-top: 1px solid #ddd; margin: 28px 0; } This article provides a comprehensive reference for troubleshooting ServiceNow SQL API issues, including minimum requirements, prerequisites, common ODBC and JDBC driver errors, and frequently asked questions. Minimum Requirements and Supported Software The following minimum versions are required to use the SQL API v1.0. TypeSupported VersionServer (ServiceNow release)Australia Patch 1 or Zurich Patch 8ODBC Client Driverv3.0JDBC Client Driverv2.0Java Runtime (JDK)JDK 17 Supported Windows Operating Systems (ODBC Driver) The ServiceNow ODBC driver supports installation on the following Windows operating systems: Windows XPWindows VistaWindows 7Windows 8Windows 10Windows 11Windows Server 2003Windows Server 2008Windows Server 2012Windows Server 2016Windows Server 2019Windows Server 2022 Usage Limitations The SQL API enforces the following rate limits to ensure system stability and performance: ODBC: 500 queries per hourJDBC: 500 queries per hour These limits are independent of each other and apply regardless of which service account is used. The limit is assessed per hour based on the wall clock. Once exceeded, subsequent queries are rejected until the rate limit window resets. If you need the limit increased, contact ServiceNow Technical Support. Prerequisites Checklist Before troubleshooting any SQL API error, verify that all of the following are in place. Many common errors are caused by one or more of these prerequisites being missed. PrerequisiteDetailsSQL API plugin installedThe SQL API plugin must be installed on your ServiceNow instance. This plugin is only supported on Zurich Patch 8 (ZP8) and Australia Patch 1 (AP1) or later.RaptorDB Pro entitlementAn active RaptorDB Pro license is required to use SQL API. The plugin will not function if you downgrade to RaptorDB Standard, even if it remains installed.JDK 17 installedJDK 17 must be installed on the client machine for both ODBC and JDBC drivers.Non-interactive service accountA dedicated service account must be created with Identity Type set to Machine (not User).MFA disabledMulti-factor authentication must be disabled for the non-interactive service account.Correct roles assignedAssign the sn_odbc_rest_access role for ODBC connections, or the sn_jdbc_rest_access role for JDBC connections.ACLs configuredBoth egress_sql and read ACL records with the proper roles must be created for each table the service account needs to query.IP address allowlistedThe client machine IP address must be added to the SQL API Authentication Policy IP filter criteria.Correct URL formatJDBC: jdbc:servicenow://<instance>.servicenow.comODBC: url=https://<instance>.service-now.comEnsure no extra whitespace before or after the URL in custom properties.Driver architecture match (ODBC)The ODBC driver architecture (32-bit or 64-bit) must match the architecture of the BI tool you are connecting from. Troubleshooting ODBC Errors The following are common errors encountered when using the ServiceNow SQL API ODBC driver, along with their causes and step-by-step resolutions. To locate ODBC client-side log files, navigate to: <drive>:\ProgramData\ServiceNow\odbc\logging\odbc.log Note: After following the resolution steps for any ODBC error, make sure to completely close the ODBC Data Source Administrator, iSQL command line, or your BI tool and reopen it to clear the cache before retrying the connection. Error: Cannot execute the query. Required to provide authentication information This error appears when the service account is not properly configured for non-interactive authentication. The ServiceNow instance log may also show one of the following messages: User Not AuthenticatedInteractive user identified: [user_id] Resolution: Open your ServiceNow instance and navigate to the service account user record.Verify that Identity Type is set to Machine. If it is set to User, update it to Machine and save.Confirm that MFA is disabled for this account. Navigate to the user record and ensure no MFA enforcement is applied.Navigate to All > SQL API > Authentication Policies and confirm that the client machine IP address is listed in the IP filter criteria. If it is missing, add it and save. For more information, see Adaptive Authentication.Retry the connection. Error: This user is not allowed access to table [table_name] This error indicates that the service account does not have the required permissions to query the specified table. Resolution: Navigate to the service account user record and confirm that the sn_odbc_rest_access role is assigned.Navigate to All > Security > Access Control (ACL) and verify that both of the following ACL records exist for the table in question: An ACL of type egress_sql for the table, with the role assigned to the service account included.An ACL with read operation for the table, with the role assigned to the service account included. If either ACL is missing, create it and assign the appropriate role.Retry the query. Error: Failed to Initialize the Service Component / Failed to create the Core Service component These errors typically indicate a mismatch between the ODBC driver architecture and the BI tool, or an incorrect JVM configuration. Resolution: Confirm whether your Windows operating system is 32-bit or 64-bit.Confirm whether the installed ServiceNow ODBC driver is 32-bit or 64-bit. The driver architecture must match the architecture of the BI tool you are connecting from, not necessarily the OS. If there is a mismatch, uninstall the current driver and install the correct version.Open the Microsoft Management Console (MMC) as administrator. Navigate to Services > ServiceNow_ODBC > Service Settings > IP Parameters. Click on ServiceJVMLocation and verify that it points to the correct jvm.dll path under JDK 17. Make sure the bitness of the JDK matches the bitness of the driver — if a 32-bit driver is installed, use 32-bit JDK 17.Note that the jvm.dll file path must be from a full JDK installation. Installing only the JRE (Java Runtime Environment) and selecting jvm.dll from it is not sufficient — the full JDK 17 must be installed and the path must point to the jvm.dll within that JDK installation.Save the configuration and close the Microsoft Management Console. Test the connection again from the ODBC Data Source Administrator or your BI tool. Error: Cannot connect to instance. java.lang.NoClassDefFoundError: org/bouncycastle/asn1/cms/CMSObjectIdentifier This error occurs when the ServiceJVMClassPath is not set correctly and the required BouncyCastle dependency JAR files cannot be located. These JAR files are included in the SQL API v1.0 ZIP download under the ODBC folder. Resolution: Extract the SQL API v1.0 ZIP file if you have not already done so. Locate the following JAR files under the ODBC folder: bc-fips-2.0.0.jarbcpkix-fips-2.0.7.jarbcutil-fips-2.0.3.jar Open the ServiceNow SQL API - ODBC Manager and navigate to Manager (local configuration) > <drive>:\Program Files\ServiceNow\ODBC\cfg\oadm.ini > Services > ServiceNow_ODBC > Service Settings > IP Parameters.Open the ServiceJVMClassPath parameter.Append the paths to the three JAR files to the existing value, separated by semicolons. For example: <path-to-folder>\bc-fips-2.0.0.jar;<path-to-folder>\bcpkix-fips-2.0.7.jar;<path-to-folder>\bcutil-fips-2.0.3.jar Save the configuration.Save the configuration and close the ODBC Manager. Test the connection again from the ODBC Data Source Administrator or your BI tool.If you move the JAR files to a different location after the initial setup, update the paths in the ServiceJVMClassPath parameter accordingly. Also ensure that the logged-in or admin user has read access to the new location, otherwise the service will not be able to load the JAR files. Error: Test connection failed from ODBC Data Source Administrator This is a general connection failure that can have several causes. Work through the following checks in order. Resolution: Confirm that Identity Type is set to Machine on the service account.Confirm that MFA is disabled for the service account.Check the Connection URL in the ODBC custom properties. Ensure there is no extra whitespace before or after the URL value.Confirm that the client machine IP address is included in the SQL API Authentication Policy IP filter criteria. For more information, see Adaptive Authentication.Close the ODBC Data Source Administrator window completely and test the connection again from the ODBC Data Source Administrator or your BI tool. This clears any cached connection state that may be causing stale failures. Troubleshooting JDBC Errors The following are common errors encountered when using the ServiceNow SQL API JDBC driver, along with their causes and step-by-step resolutions. Error: User Not Authenticated { "error": { "message": "User Not Authenticated", "detail": "Required to provide Auth information" }, "status": "failure" } Resolution: Verify that the username and password entered in the JDBC connection configuration are correct.Navigate to the service account user record in ServiceNow and confirm that Identity Type is set to Machine.Confirm that MFA is disabled for the service account.Navigate to All > SQL API > Authentication Policies and confirm that the client machine IP address is listed in the IP filter criteria. If missing, add it and save. For more information, see Adaptive Authentication.Retry the connection. Error: Interactive user not allowed. Request blocked for user: [user_id] This error occurs when the service account is configured as an interactive user instead of a non-interactive machine account. The SQL API does not permit interactive users to make requests. Resolution: Log in to your ServiceNow instance.Navigate to All > User Administration > Users and open the service account user record.Locate the Identity Type field and change the value from User to Machine.Save the record.Retry the JDBC connection. Error: Failed API level ACL validation / This user is not allowed access to table [table_name] { "error": { "message": "User Not Authorized", "detail": "Failed API level ACL Validation" }, "status": "failure" } This error occurs when the service account does not have the required role or when the necessary ACLs are missing or inactive for the table being queried. Resolution: Navigate to the service account user record in ServiceNow and confirm that the sn_jdbc_rest_access role is assigned. If it is missing, assign it and save.Navigate to Adaptive Authentication > Authentication Policies > All Policies and open the SQL API Authentication Policy. Confirm that the client machine IP address is listed in the IP filter criteria. If it is missing, add it and save.Navigate to All > Security > Access Control (ACL) and verify that both of the following ACL records exist for the table in question: An ACL of type egress_sql for the table, with the role assigned to the service account included.An ACL with read operation for the table, with the role assigned to the service account included. If either ACL record exists but is set to inactive, open it and set it to active.If either ACL is missing, create it and assign the appropriate role.If the query runs without any error but returns no results, verify that both the read and egress_sql ACLs are present and active for the table. Missing or inactive ACLs can silently restrict data access without throwing an explicit error.Retry the query. Error: Rate limit exceeded { "error": { "message": "Rate limit exceeded", "detail": "Rate limit of 500 requests per hour for JDBC Rest connector exceeded" }, "status": "failure" } This error occurs when more than 500 JDBC queries have been executed within the current hour window. The rate limit applies to JDBC calls independently of ODBC calls and resets based on the wall clock hour. Resolution: Wait for the current rate limit window to reset. The limit resets based on the wall clock hour.If your use case consistently requires more than 500 JDBC queries per hour, contact ServiceNow Technical Support to discuss options. Error: Transaction cancelled — maximum execution time exceeded { "error": { "message": "Exception while executing request: Transaction cancelled: maximum execution time exceeded", "detail": "Transaction cancelled: maximum execution time exceeded. Check logs for error trace or enable glide.rest.debug property to verify REST request processing" }, "status": "failure" } The SQL API runs on top of the ServiceNow REST layer, which enforces a maximum transaction time of 300 seconds. The default query timeout is 5 minutes. If a query exceeds this limit it is terminated and no partial data is returned. Resolution: Review your query and optimize it: Add WHERE clauses that filter on indexed fields to reduce the data scanned.Avoid SELECT * — specify only the columns you need.Use LIMIT statements to control result set size.Break large queries into smaller, targeted queries if necessary. To review the execution trace and understand where the query is spending time, set the System Property glide.rest.debug to true in the System Properties [sys_properties] table. Remember to set it back to false after debugging to avoid performance overhead. For guidance on debugging inbound REST queries, see Debugging REST Queries.For information on Transaction Quota Rules that govern these limits, refer to the Transaction Quotas documentation. Frequently Asked Questions What authentication methods are supported by the SQL API? The initial release of SQL API supports basic authentication only. When connecting to your ServiceNow instance using either an ODBC or JDBC client, you must provide the proper service account credential as configured by your ServiceNow administrator. Why does SQL API require a service account? One of the main use cases for SQL API is Business Intelligence (BI). Primary uses for BI is to generate dashboards and reports. Dashboards and reports built using individual user accounts would break if, for example, the user leaves the company. By using service accounts these dashboards and reports would continue to function. How do I manage credentials for SQL API connections? Credentials are managed through your ServiceNow instance. You must create a dedicated service account with the appropriate permissions via default roles provided with the SQL API plugin (sn_odbc_rest_access or sn_jdbc_rest_access role) to access data through the SQL API. Typically, a service account is given read access to certain tables to achieve the needs of a group of people. You can create multiple service accounts based on different use cases. What permissions are required to use the SQL API? You must have either the sn_odbc_rest_access role for ODBC connections or the sn_jdbc_rest_access role for JDBC connections. Additionally, Access Control Lists (ACLs) determine which tables and data you can access. By default, the SQL API checks access at the table, row, and field level for every query. This follows ServiceNow's secure-by-default approach. The SQL API validates all ACLs in your instance record by record, which may result in longer response times. This is expected behavior. If your use case does not require row and field-level checks — for example, a Business Intelligence integration — you can turn them off by assigning the sn_sql_api_privileged_mode role to the service account. Table-level ACL checks remain in effect and cannot be turned off. Does the SQL API support asynchronous queries? No, the SQL API executes all queries synchronously. Your client will wait for the query to complete before receiving results. Is pagination supported for large result sets? No, pagination is not supported. You should use WHERE clauses and LIMIT statements to control the size of your result sets. What is the default query timeout? The default query timeout is 5 minutes. If your query exceeds this limit, it will be terminated. In case of a query timeout, SQL API will not return a partial data set to avoid confusion. How many concurrent queries can I run? The number of concurrent queries your instance can handle depends on its configuration and available application nodes. Any queries that exceed this limit are automatically queued. Are there rate limits for SQL API queries? Yes, the SQL API enforces a rate limit of 500 queries per hour per user account. The limit is assessed per hour based on the wall clock. If you should increase this limit, contact ServiceNow tech support. What happens if I exceed the rate limit? If you exceed 500 queries per hour, subsequent queries will be rejected until the rate limit window resets. Which ODBC clients have been tested with the SQL API? The SQL API has been tested with the following ODBC clients: iSQLMicrosoft Power BIMicrosoft Excel Which JDBC clients have been tested with the SQL API? The SQL API has been tested with the following JDBC clients: DBVisualizerDBeaver Can I use other database clients not listed as tested? While the SQL API should work with any industry standard ODBC or JDBC client, the clients listed before have been officially tested and verified by ServiceNow. ServiceNow continues to evaluate and test new clients, and we will update the list of officially tested clients in our documentation as appropriate. What happens if I download and try to use the SQL API client without the appropriate license? You must have a RaptorDB Pro entitlement to activate the SQL API server-side plugin. The SQL API client is freely available for download by anyone with a valid account to the ServiceNow Store. However, the SQL API client would not be able to connect to the ServiceNow instance until you enable the server-side plugin. How do I verify that I have the correct license before downloading the SQL API client? Before downloading the SQL API drivers, confirm with your ServiceNow administrator that your instance has an active RaptorDB Pro entitlement. You can verify this in your ServiceNow instance under Application Manager to check if the SQL API plugin is available for installation. However, if you downgrade to RaptorDB Standard, the plugin will no longer work, even though it remains installed on your instance. You must maintain an active RaptorDB Pro license to use the SQL API. Prior to SQL API, ServiceNow provided a SOAP-based ODBC client that was free to customers. SQL API is based on REST. If I currently use the SOAP-based ODBC client, what should I do to migrate to the new REST-based SQL API client? If you have an active RaptorDB Pro entitlement, you can migrate from the SOAP client to the REST-based SQL API client by completing the configuration on both the server and client sides. Refer to the Configuring SQL API documentation for detailed step-by-step instructions. After migration, verify your existing reports, dashboards, etc. work as expected. Should my existing reports and dashboards be reconfigured after migrating to the REST client? Yes, you must update your BI tools and applications to use the new ODBC DSN configured for the REST-based SQL API client. Your SQL queries may remain the same, but the connection configuration must be updated. Can I have both SOAP and REST ODBC clients installed on the same machine? No. The installer automatically removes the previous SOAP-based driver version before installing the new REST-based one. Are there SQL clauses or functions supported in JDBC but not in ODBC, or vice versa? Yes. There are differences in the SQL clauses and functions supported between the JDBC and ODBC drivers. For a full list, refer to the SQL API — JDBC-Only Supported Functions and Clauses knowledge base article.