bug: service account with DWD configured gives cryptic "failedPrecondition" with no actionable error message

[sutanto62]

Environment

• gws 0.22.5 / macOS Darwin 24.6.0
• service-account.json present at ~/.config/gws/service-account.json
• Domain-wide delegation configured in Google Admin for the service account

Problem

When a service account key file is in place and DWD is correctly configured in Google Workspace Admin, calling any Gmail/Drive API returns a cryptic error with no actionable guidance:

{
  "error": {
    "code": 400,
    "message": "Precondition check failed.",
    "reason": "failedPrecondition"
  }
}
error[api]: Precondition check failed.

The root cause is that yup_oauth2 builds the service account JWT without a sub claim, so Google's token endpoint mints a token for the service account identity itself (which has no Gmail/Drive mailbox) rather than the delegated user.

Steps to reproduce

1. Place a service account key JSON at ~/.config/gws/service-account.json
2. Configure DWD in Google Admin → Security → API Controls → Domain-wide Delegation
3. Run: gws gmail users messages list --params '{"userId": "me"}'
4. Run: gws gmail users messages list --params '{"userId": "user@domain.com"}'

Both return failedPrecondition.

Additional confusion: auth status is misleading

{
  "auth_method": "oauth2",
  "credential_source": "none",
  "plain_credentials": "/Users/.../.config/gws/service-account.json",
  "plain_credentials_exists": true
}

auth_method shows oauth2 and credential_source shows none even though the service account file is found (plain_credentials_exists: true). This makes it impossible to tell whether the file is being used and in what mode.

Expected behaviour

One of:

• A clear error: "Service account detected but no impersonation subject set. Use --subject user@domain.com or GOOGLE_WORKSPACE_CLI_SUBJECT to enable DWD."
• auth status should show auth_method: service_account when a service account key is active

Workaround

Pre-generate a DWD token using google-auth and pass it via GOOGLE_WORKSPACE_CLI_TOKEN:

import google.oauth2.service_account, google.auth.transport.requests
creds = google.oauth2.service_account.Credentials.from_service_account_file(
    '~/.config/gws/service-account.json',
    scopes=['https://www.googleapis.com/auth/gmail.modify'],
    subject='user@domain.com'
)
creds.refresh(google.auth.transport.requests.Request())
# then: GOOGLE_WORKSPACE_CLI_TOKEN=<creds.token> gws ...

Related

• feat: Re-add service account impersonation to support executive assistant workflows #632 — feature request to re-add --subject / GOOGLE_WORKSPACE_CLI_SUBJECT

This issue is specifically about the error UX — even while the full feature (#632) is pending, a better error message or correct auth status output would make DWD failures debuggable.

[eagle19900203-boop]

Environment

• gws 0.22.5 / macOS Darwin 24.6.0
• service-account.json present at ~/.config/gws/service-account.json
• Domain-wide delegation configured in Google Admin for the service account

Problem

When a service account key file is in place and DWD is correctly configured in Google Workspace Admin, calling any Gmail/Drive API returns a cryptic error with no actionable guidance:

{
  "error": {
    "code": 400,
    "message": "Precondition check failed.",
    "reason": "failedPrecondition"
  }
}
error[api]: Precondition check failed.

The root cause is that yup_oauth2 builds the service account JWT without a sub claim, so Google's token endpoint mints a token for the service account identity itself (which has no Gmail/Drive mailbox) rather than the delegated user.

Steps to reproduce

1. Place a service account key JSON at ~/.config/gws/service-account.json
2. Configure DWD in Google Admin → Security → API Controls → Domain-wide Delegation
3. Run: gws gmail users messages list --params '{"userId": "me"}'
4. Run: gws gmail users messages list --params '{"userId": "user@domain.com"}'

Both return failedPrecondition.

Additional confusion: auth status is misleading

{
  "auth_method": "oauth2",
  "credential_source": "none",
  "plain_credentials": "/Users/.../.config/gws/service-account.json",
  "plain_credentials_exists": true
}

auth_method shows oauth2 and credential_source shows none even though the service account file is found (plain_credentials_exists: true). This makes it impossible to tell whether the file is being used and in what mode.

Expected behaviour

One of:

• A clear error: "Service account detected but no impersonation subject set. Use --subject user@domain.com or GOOGLE_WORKSPACE_CLI_SUBJECT to enable DWD."
• auth status should show auth_method: service_account when a service account key is active

Workaround

Pre-generate a DWD token using google-auth and pass it via GOOGLE_WORKSPACE_CLI_TOKEN:

import google.oauth2.service_account, google.auth.transport.requests
creds = google.oauth2.service_account.Credentials.from_service_account_file(
    '~/.config/gws/service-account.json',
    scopes=['https://www.googleapis.com/auth/gmail.modify'],
    subject='user@domain.com'
)
creds.refresh(google.auth.transport.requests.Request())
# then: GOOGLE_WORKSPACE_CLI_TOKEN=<creds.token> gws ...

Related

• feat: Re-add service account impersonation to support executive assistant workflows #632 — feature request to re-add --subject / GOOGLE_WORKSPACE_CLI_SUBJECT

This issue is specifically about the error UX — even while the full feature (#632) is pending, a better error message or correct auth status output would make DWD failures debuggable.