@Rocky We are using iceberg for our starrocks and ocassionally we see REST CATALOG API error, cannot authorized to the DB, however after restarting the starrocks it would work. Is there any bug with starrocks for this issue ?

Based on your description, the intermittent authorization error you're seeing with the Iceberg REST Catalog is a known behavior (and in some cases, a configuration issue) typically related to OAuth2 access token expiration. Why it happens When you create or initialize an Iceberg REST Catalog in StarRocks, it obtains an initial OAuth2 access token. These tokens usually have a short lifespan (often 1 hour). * The Problem: If StarRocks cannot successfully refresh this token, subsequent requests to the REST Catalog will fail with a "Not authorized" or "401 Unauthorized" error. * Why a restart works: Restarting StarRocks forces the catalog to re-initialize and obtain a fresh token from the authentication server, which works until that new token expires again. Known Causes and Bugs 1. Token Exchange is not enabled on your IdP StarRocks requires the Token Exchange (RFC 8693) flow to be enabled on your Identity Provider (e.g., Keycloak, Okta, or your REST Catalog server). If this is disabled, StarRocks cannot exchange an expiring token for a new one. * Fix: Ensure "Standard Token Exchange" or "Token Exchange" is enabled for the client ID used by StarRocks in your IdP settings. 2. Malformed OAuth2 Request Bug (Issue #61253) There is a documented bug in StarRocks where the client incorrectly handles the

iceberg.catalog.oauth2.scope

parameter or sends a malformed request to the OAuth2 token endpoint. This is particularly common when connecting to catalogs like Apache Polaris. * Status: This was reported in 2025 and is addressed in newer versions of the StarRocks Iceberg connector. 3. Configuration Inconsistencies In some StarRocks versions, there were inconsistencies between the documented property names and the actual implementation for REST catalogs. * Recommendation: Verify your catalog properties. For example, some versions required

oauth2.server-uri

instead of

iceberg.catalog.oauth2.server-uri

. Check your version-specific documentation or try both formats if you see persistent "Not authorized" errors during setup. Recommended Troubleshooting 1. Check StarRocks Version: If you are on a version older than 3.3.0 or 4.0, consider upgrading. Major improvements to Iceberg REST Catalog security and token handling were introduced in StarRocks 4.0 (including JWT passthrough and better vended credentials support). 2. Enable Token Exchange: Verify with your security/identity team that the "Token Exchange" flow is permitted for your credentials. 3. Check FE Logs: Look for

OAuth2Client

or

RESTCatalog

errors in your

fe.log

around the time the error occurs. It will often reveal if a refresh attempt failed. 4. Try `token-refresh-enabled`: Although enabled by default in recent Iceberg libraries, you can explicitly ensure it is set (if supported by your version's properties). If the issue persists despite these changes, it is recommended to capture the specific error from the

fe.log

and share it on the StarRocks Slack or open a GitHub issue, as it may be a specific regression in your current version. References • data_source/catalog/iceberg/iceberg_rest_security.md • data_source/catalog/iceberg/iceberg_catalog.md

@Rocky I am using apache polaris as my iceberg and I do not see any errors about token refresh in starrocks logs. So why would I see these unauthorized errors ? and it gets fixed after restart. I am using starrocks 4.1, is there any bug using polaris with starrocks 4.1 ?

While there isn't a single "StarRocks 4.1 Polaris Bug" label, your symptoms (working at first, then "unauthorized" until a restart) align perfectly with OAuth2 token refresh failures that have been documented in StarRocks when interacting with Apache Polaris. Specifically, there is a known issue involving how StarRocks handles the OAuth2

scope

parameter and token refresh cycles with REST catalogs like Polaris. 1. The "Malformed Scope" Bug (Issue #61253) There is a documented bug where StarRocks sends a malformed or incompatible

scope

parameter during the OAuth2 token request/refresh process. * The Symptom: Initial connection works because the first token is obtained (or sometimes the catalog allows a blank scope initially). However, when StarRocks attempts to refresh the token (typically every 1 hour), Polaris rejects the refresh request because the scope parameter is improperly formatted. * The "No Log" Mystery: If the refresh logic fails internally or receives a response it doesn't handle gracefully, it may not log a clear "Token Refresh Failed" message. Instead, the next query simply sends an expired token, causing Polaris to return a

401 Unauthorized

error. * Why a restart fixes it: A restart forces StarRocks to drop the old session and perform a fresh

POST /v1/oauth/tokens

call with initial credentials, which works until that new token expires. 2. Version-Specific Behavior in 4.1 StarRocks 4.1 introduced deeper integration for Vended Credentials and JWT Passthrough. If you are using Polaris, ensure you aren't inadvertently hitting a mismatch between these new features and your catalog configuration. * Recommendation: If you are on 4.1.0, try upgrading to 4.1.1 or later. Several stability fixes for the Iceberg REST connector and JNI-based credential handling were bundled into the 4.1.1+ releases. 3. Recommended Workaround/Configuration To stabilize the connection with Polaris in StarRocks 4.1, verify the following properties in your

CREATE EXTERNAL CATALOG

statement: 1. Explicitly Disable Scope (if applicable): If Polaris is picky about the scope, you can try setting an empty scope or ensuring the scope matches exactly what Polaris expects. 2. Verify Credential Format: Ensure you are using the property:

"iceberg.catalog.oauth2.credential" = "<client_id>:<client_secret>"

3. Check for "Vended Credentials": If you have

"iceberg.catalog.vended-credentials-enabled" = "true"

, StarRocks relies on Polaris to provide temporary S3/GCS tokens. If the REST token (the OAuth2 one) expires, the vending stops. How to verify the bug Before restarting next time the error occurs, try to run a simple

CURL

command from the StarRocks FE node to the Polaris token endpoint using the same credentials. If the

CURL

works but StarRocks does not, it confirms StarRocks is holding onto an expired/stale token state. Summary: This is a known issue related to token lifecycle management in the REST connector. Upgrading to the latest patch of 4.1 (e.g., 4.1.3 or higher) is the most direct fix, as these versions contain refinements for the Iceberg REST OAuth flow. References • data_source/catalog/iceberg/iceberg_rest_security.md • data_source/catalog/iceberg/iceberg_rest_s3.md • data_source/catalog/iceberg/iceberg_catalog.md

hi @Santosh Kumar Katkam did you solve the issue? I facing similar issue when use iceberg rest catalog connecto to gravitino with oauth, client-id:client-secret

Hi @Phước Hồ we have seeing this issue occasionally, not sure about the root cause. We have to restart starrocks whenever we have seen this error. After upgrading it to the latest starrocks version, we haven't seen this issue. ( So probably some bug with old version of starrocks )