Metadata.Service %q must be one trimmed command segment

Error message

Metadata.Service %q must be one trimmed command segment

What it means

Metadata.Service must be exactly one command segment: the raw value must equal its whitespace-trimmed form (no leading/trailing spaces) and must contain no spaces, tabs, carriage returns, newlines, or slashes. Slashes would imply nested paths, which the metadata model does not allow for Service.

Source

Thrown at shortcuts/common/typed_compiler.go:94

			conditional.Params = append([]string(nil), conditional.Params...)
			if conditional.Requirement == "" {
				conditional.Requirement = typedScopeRequired
			}
		}
		identities[identity] = authorization
	}
	metadata.Authorization.Identities = identities
	metadata.Authorization.IdentityOrder = append([]typedIdentity(nil), metadata.Authorization.IdentityOrder...)
	return metadata
}

func validateCommandMetadata(metadata typedCommandMetadata) error {
	service := strings.TrimSpace(string(metadata.Service))
	if service == "" {
		return fmt.Errorf("Metadata.Service is required")
	}
	if service != string(metadata.Service) || strings.ContainsAny(service, " \t\r\n/") {
		return fmt.Errorf("Metadata.Service %q must be one trimmed command segment", metadata.Service)
	}
	command := strings.TrimSpace(metadata.Command)
	if command == "" {
		return fmt.Errorf("Metadata.Command is required")
	}
	if command != metadata.Command || strings.ContainsAny(command, " \t\r\n/") {
		return fmt.Errorf("Metadata.Command %q must be one trimmed command segment", metadata.Command)
	}
	if !strings.HasPrefix(command, "+") {
		return fmt.Errorf("Metadata.Command %q must start with '+'", metadata.Command)
	}
	if command == "+" {
		return fmt.Errorf("Metadata.Command must contain a name after '+'")
	}
	if strings.TrimSpace(metadata.Description) == "" {
		return fmt.Errorf("Metadata.Description is required")
	}
	switch metadata.Risk {

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Replace Service with a single lowercase segment, e.g. "im"; put the readable name in Metadata.Description.
Move any path-like portion into Metadata.Command (which starts with '+') rather than Service.
Trim the value at its source so no leading/trailing whitespace is stored.
If you need a compound name, use a hyphen or dot if permitted by convention — never a slash or space.

Example fix

// before
Metadata: common.Metadata{Service: "docs/wikis", Command: "+create"}
// after
Metadata: common.Metadata{Service: "docx", Command: "+create"}

Defensive patterns

Strategy: validation

Validate before calling

func validServiceSegment(s string) bool {
  t := strings.TrimSpace(s)
  return t != "" && t == s && !strings.ContainsAny(t, " \t\r\n/")
}

Prevention

Use a single lowercase identifier (e.g. "im", "docx") for Service; never prose or API paths.
Store service names as constants so formatting/whitespace cannot creep in.
Keep readable wording in Metadata.Description instead of Service.

When it happens

Trigger: CompileCommandDefinition with Service values like "im " (trailing space), " im", "instant messaging", "docs/wikis", or any multi-word or path-like string.

Common situations: Writing a human-readable label ("Instant Messaging") instead of the single segment identifier; copying an API path ("im/v1/chats") into Service; trailing whitespace from an editor or string concatenation.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/1722152515a5872d. Report an issue: GitHub.