[direct] UpdateApp sends unsupported forward_user_access_token to downlevel workspaces

[jefbarn]

Describe the issue

bundle deploy with CLI v1.14.1 fails when updating an existing Databricks App against an Azure Databricks workspace whose Apps API does not yet accept forward_user_access_token in an UpdateApp field mask.

The field is not declared anywhere in the bundle and is absent from databricks apps get, but the direct engine includes it in its static update mask. The workspace rejects the entire request with HTTP 400. The same bundle and workspace deploy successfully with CLI v1.12.0.

This looks like a downlevel-compatibility bug: the CLI assumes the target workspace supports a field introduced in the SDK used by CLI v1.13.0. It should either derive the update mask from the fields being changed or otherwise avoid sending fields unsupported by the target service.

This is related to #6400, which documents the static UpdateApp mask, but this report captures a hard deployment failure caused by one of those unconditional fields.

Configuration

A minimal existing app that requires any supported app update should reproduce it. Neither forward_user_access_token nor user_api_scopes is configured.

bundle:
  name: example-app

resources:
  apps:
    example:
      name: example-app-dev
      description: Example app
      compute_size: MEDIUM
      resources:
        - name: sql-warehouse
          sql_warehouse:
            id: <warehouse-id>
            permission: CAN_USE

The affected app already had an active deployment and several declared resources. Updating the bundle's Git commit caused the deployment to enter the UpdateApp path.

Steps to reproduce the behavior

1. Deploy and run the app once so it has an active deployment.
2. Change a supported app property or deploy a new Git commit so the app resource is updated.
3. Run databricks bundle deploy -t dev with CLI v1.14.1.
4. Observe the rejected UpdateApp request.
5. Run the same deployment with CLI v1.12.0; it completes successfully.

Expected Behavior

The CLI updates and deploys the app. A current CLI should tolerate a workspace running a downlevel Apps API by omitting unsupported fields, especially fields that are neither configured nor being changed.

Actual Behavior

The deployment fails before updating the app:

Error: cannot update resources.apps.example: updating id=example-app-dev: Invalid update mask.
Only description, budget_policy_id, usage_policy_id, resources, user_api_scopes,
compute_size, compute_min_instances, compute_max_instances, git_repository,
git_source, telemetry_export_destinations, compatibility_flags are allowed.
Supplied update mask: description, budget_policy_id, usage_policy_id, resources,
user_api_scopes, forward_user_access_token, compute_size, compute_min_instances,
compute_max_instances, git_repository, telemetry_export_destinations
(400 INVALID_PARAMETER_VALUE)

Endpoint: POST https://<workspace-host>/api/2.0/apps/example-app-dev/update
HTTP Status: 400 Bad Request
API error_code: INVALID_PARAMETER_VALUE

databricks apps get example-app-dev -o json omits forward_user_access_token, so it is not being round-tripped from the existing app.

OS and CLI version

• Databricks CLI v1.14.1
• macOS 26.6.2, arm64
• Azure Databricks
• Direct deployment engine

Is this a regression?

Yes. The identical bundle, target, workspace, app, and Git commit deploy successfully with CLI v1.12.0. CLI v1.14.1 fails consistently with the update-mask error above.

CLI v1.13.0 bumped databricks-sdk-go from v0.170.0 to v0.171.0; SDK v0.171.0 added ForwardUserAccessToken to apps.App and apps.AppUpdate.

Detailed plan

The plan showed the existing app as an update and did not indicate that an unsupported field would be added to the request mask.

Debug Logs

The redacted API error and complete supplied/allowed update masks are included above. The workaround was to run the same deployment with the official v1.12.0 binary, after which bundle deployment, app start, and post-deploy verification all succeeded.