Skip to content

fix: clear error when Bytebase server predates 3.17.0#192

Open
vsai12 wants to merge 2 commits intomainfrom
fix/client-version-mismatch-error
Open

fix: clear error when Bytebase server predates 3.17.0#192
vsai12 wants to merge 2 commits intomainfrom
fix/client-version-mismatch-error

Conversation

@vsai12
Copy link
Copy Markdown
Contributor

@vsai12 vsai12 commented Apr 20, 2026

Summary

  • Fail fast at client init with an explicit version-mismatch message when the Bytebase server returns a legacy bare-UUID workspace value, instead of letting a cryptic server-side error surface later.

Why

Bytebase 3.16.x servers populate the actuator workspace field with a bare UUID (the proto field was named workspace_id at the time). Starting in 3.17.0, the provider no longer prepends workspaces/ to that value (it expects the server to return the fully-qualified workspaces/{id}). On a 3.16.x server, the bare UUID is forwarded as the IAM policy resource field, and the server's validateWorkspaceResource check rejects it with:

Error: invalid_argument: invalid workspace resource "<uuid>"

…which gives the user no hint that the real answer is "upgrade the Bytebase server." Other Terraform providers (hashicorp/kubernetes, aws, google, vault) handle backend version skew by failing fast at client init with a clear message; this PR applies the same pattern.

The fix

In client.NewClient, after fetching actuator info:

if !strings.HasPrefix(workspace, "workspaces/") {
    return nil, errors.Errorf(
        "legacy workspace value %q (expected %q); this provider version requires Bytebase >= 3.17.0. Upgrade the server, or pin the provider to \"~> 3.16\".",
        workspace, "workspaces/<id>",
    )
}

Test plan

No unit tests added — client/ has no test scaffolding today and standing it up for one branch is disproportionate to the change. Verified manually:

  • Point provider against Bytebase 3.16.x server → terraform plan on a bytebase_iam_policy resource → fails at provider init with the new message (not at IAM call site with the cryptic error).
  • Point provider against Bytebase 3.17.0+ server → terraform plan succeeds unchanged.
  • go vet ./..., gofmt, go build ./... all clean locally.

Bytebase 3.16.x servers emit a bare UUID in the actuator `workspace`
field; since 3.17.0 the provider no longer prepends `workspaces/` to
that value, so the bare UUID was forwarded as the IAM policy resource
and the server rejected it with a cryptic
`invalid workspace resource "<uuid>"` error.

Fail fast at client init with an explicit version-mismatch message
instead, matching how other Terraform providers handle backend version
skew.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@d-bytebase d-bytebase requested a review from ecmadao April 20, 2026 18:21
Drop the trailing period and restructure the multi-sentence error
into a single sentence so the string no longer ends with punctuation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Comment thread client/client.go
if workspace == "" {
return nil, errors.New("actuator returned empty workspace name; cannot initialize provider")
}
if !strings.HasPrefix(workspace, "workspaces/") {
Copy link
Copy Markdown
Collaborator

@ecmadao ecmadao Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before 3.17.0 we only have the workspace ID in the actuator https://github.com/bytebase/bytebase/blob/release/3.16.1/backend/api/v1/actuator_service.go#L151, so it will never trigger this error, always return in line112

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants