UX: Add Catalog form has misleading labels and unsafe defaults for OAuth2 + Snowflake-Polaris

[antoniocali]

Summary

The "Add New Catalog" form in the Fusion UI (Optimizer → Catalogs → Add New Catalog) has a few UX issues that cost real debugging time when setting up a REST catalog against Snowflake-hosted Apache Polaris. Filing as one issue because they're all in the same dialog.

1. "S3 Path" field is misleadingly labeled

The field labeled S3 Path (with a * required marker) maps to the iceberg_s3_path writer property, which — per OLake's own docs — is the Polaris catalog name, not an S3 URI:

iceberg_s3_path: Name of the Polaris catalog

The current label invites the user to type s3://bucket/..., which is wrong. Either:

• Rename the field to "Polaris Catalog Name" (or "Iceberg Catalog Identifier"), or
• Update the tooltip to clarify that this is a logical catalog name, with an explicit example: "Polaris catalog name (e.g. airflow, production_db) — not an S3 URI".

2. "REST Enable Signature V4" defaults to ON and silently breaks OAuth2 + Snowflake-Polaris

The most common Polaris deployment today is Snowflake's hosted offering, which uses OAuth2 client-credentials auth — not AWS SigV4. With the SigV4 toggle ON (the form default), the Iceberg Java client wraps its HTTP client with RESTSigV4Signer, which then tries to sign even the OAuth token-fetch request with AWS SigV4. The Spark optimizer pod has no AWS creds (intentionally — we use Polaris credential vending), so the SDK's default credential chain fails before OAuth even runs:

software.amazon.awssdk.core.exception.SdkClientException:
  Unable to load credentials from any of the providers in the chain …
    at org.apache.iceberg.aws.RESTSigV4Signer.process(RESTSigV4Signer.java:88)
    at org.apache.iceberg.rest.HTTPClient.execute(HTTPClient.java:305)
    at org.apache.iceberg.rest.auth.OAuth2Util.fetchToken(OAuth2Util.java:264)
    at org.apache.iceberg.rest.RESTSessionCatalog.initialize(...)

The error message points the user toward AWS credential configuration, which is the wrong direction — the actual fix is "turn SigV4 off". The signal is buried in the stack trace; nothing in the connection failure surfaces the SigV4-vs-OAuth conflict.

Suggestions (any one would help):

• Default the toggle OFF. It's only relevant for the niche case of Polaris fronted by AWS API Gateway with IAM auth. Most Polaris deployments don't need it.
• Auto-disable SigV4 when REST Auth Type is oauth2 (or none). SigV4 + OAuth2 in the same request is rarely valid.
• Surface a clearer error when SigV4 is on without AWS creds: detect the SdkClientException and explain "SigV4 is enabled but no AWS credentials are available — either disable SigV4 (likely correct for Snowflake-hosted Polaris) or provide AWS Access Key / Secret Key."

3. "REST Auth Type" should be a dropdown, not a free-text field

The current input is a text box that accepts arbitrary strings. The valid values are a small enum (looks like oauth2, plus presumably bearer, sigv4, none). A dropdown / select would:

• Prevent typos that lead to silent failures
• Self-document the valid options
• Let the UI conditionally show/hide downstream fields (e.g. hide REST Token + REST Credential when none, hide REST Signing Name/Region when not sigv4)

Context

• OLake Helm chart 0.0.18 on EKS, Fusion-enabled, Snowflake-hosted Polaris as the REST catalog
• Lost ~30 minutes debugging the SigV4 / OAuth2 conflict because the credential-chain error pointed in the wrong direction
• Once SigV4 was turned off, the catalog connected cleanly on the first attempt

Happy to send a PR for any/all of these if you'd like — (1) and (3) are pure UI changes, (2) is a server-side default flip + maybe a clearer error path.

[antoniocali]

Quick follow-up after digging into the repos: I fooled myself by filing this against olake-ui. The Add Catalog form here is fully schema-driven from the destination driver's spec — olake-ui just renders whatever /destinations/spec returns and applies no client-side label/type overrides (ui/src/common/utils/utils.ts:91-108, CatalogModal.tsx:137-141). The actual definitions of these three fields live in datazip-inc/olake:

• destination/iceberg/resources/spec.json:40-44 — iceberg_s3_path title + description (Fix Feat: frontend Initial Setup and BFF #1)
• destination/iceberg/resources/spec.json:175-179 — rest_auth_type is a free string with no enum (Fix Handle Documentation Draggable state #3)
• destination/iceberg/resources/spec.json:190-195 — rest_signing_v_4 has "default": true (Fix Modals Creation for Update for Sources , Destinations  #2)

(utils/spec/uischema.go controls layout — rest_auth_type: 12 — so widening it for a dropdown should be transparent there.)

Happy to send PRs for (1) and (3) against datazip-inc/olake to start — should I open them there, or would you prefer the issue be moved/duplicated first? Holding off on (2) until you've decided whether you want the default flipped vs. auto-disable on oauth2 vs. a clearer error path.

[merlynm20]

Thank you, @antoniocali for taking the time to share such thoughtful feedback on both the user experience and the documentation.
Contributions like yours are incredibly valuable to us. Your observations help us identify areas where we can improve usability, reduce friction, and make the documentation clearer for both new and existing users.

We truly appreciate the effort you've put into highlighting these improvements. Thank you for helping us make OLake better for the entire community.

[merlynm20]

@antoniocali Regarding the contribution piece for the destination specs that you have mentioned , @hash-data can get back to you on this.