ETCD_INVALID_ACCESS

ETCD_INVALID_ACCESS

Error message

ETCD_INVALID_ACCESS: access must be READ, WRITE, or READWRITE, got %s

What it means

permissionType validates the access string for etcd role permission grants by passing it to clientv3.StrToPermissionType. Only READ, WRITE and READWRITE are valid; any other value (case-insensitive, since it upper-cases first) fails conversion and yields this ETCD_INVALID_ACCESS coded error.

Source

Thrown at agents/drivers/etcd-go/auth.go:443

		access, err := permissionType(stringOrDefault(params, "access", ""))
		if err != nil {
			return nil, err
		}
		if _, err := client.Auth.RoleGrantPermission(ctx, role, key, rangeEnd, access); err != nil {
			return nil, err
		}
	} else {
		if _, err := client.Auth.RoleRevokePermission(ctx, role, key, rangeEnd); err != nil {
			return nil, err
		}
	}
	return map[string]bool{"updated": true}, nil
}

func permissionType(access string) (clientv3.PermissionType, error) {
	permission, err := clientv3.StrToPermissionType(strings.ToUpper(access))
	if err != nil {
		return 0, fmt.Errorf("ETCD_INVALID_ACCESS: access must be READ, WRITE, or READWRITE, got %s", access)
	}
	return permission, nil
}

View on GitHub (pinned to c0390bff16)

Solutions

Change the access value to exactly READ, WRITE, or READWRITE (case-insensitive)
Trim whitespace and check for hidden characters in config-sourced access strings
Map unsupported shorthands (e.g. "all") to the closest valid value or issue separate READ and WRITE grants
Validate the access string before calling the grant API

Example fix

// before
srv.AuthRolePermissionGrant(ctx, "app-role", key, "rw")
// after
srv.AuthRolePermissionGrant(ctx, "app-role", key, "READWRITE")

Defensive patterns

Strategy: validation

Validate before calling

func validAccess(access string) bool {
	switch strings.ToUpper(strings.TrimSpace(access)) {
	case "READ", "WRITE", "READWRITE":
		return true
	}
	return false
}

Type guard

func isPermissionType(s string) bool {
	_, err := clientv3.StrToPermissionType(strings.ToUpper(strings.TrimSpace(s)))
	return err == nil
}

Try / catch

if err := grantPermission(ctx, role, key, access); err != nil {
	if strings.Contains(err.Error(), "ETCD_INVALID_ACCESS") {
		return fmt.Errorf("invalid access %q: must be READ, WRITE or READWRITE", access)
	}
	return err
}

Prevention

Validate access strings against {READ, WRITE, READWRITE} before calling grant APIs
Trim and normalize config values (ToUpper + TrimSpace) loaded from YAML/JSON
Replace shorthand values like "rw" or "all" with the canonical permission names in configs
Add schema/enum validation for access fields in IaC and config tooling

When it happens

Trigger: Calling AuthRolePermissionGrant (via authRolePermission) with access values like "readwrite " with whitespace, "rw", "all", "read-only", or lowercase variants of unsupported words — anything StrToPermissionType rejects.

Common situations: Config files or IaC granting permissions with shorthand values ("rw", "all"); trailing whitespace or BOM in YAML/JSON config; porting etcdctl examples that use different permission vocabulary; older configs written for other auth systems.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/759eab003138551f. Report an issue: GitHub.