googlechat: credentials_file is required (the Chat app's ser

Error message

googlechat: credentials_file is required (the Chat app's service-account key, used to pull events and send replies)

What it means

googlechat.New requires the 'credentials_file' option pointing to the Chat app's service-account JSON key, used both to pull events from Pub/Sub and to send replies via the Chat API. An empty value aborts construction with this message.

Source

Thrown at platform/googlechat/googlechat.go:97

	cancel  context.CancelFunc
}

// New builds a Google Chat platform from config options.
func New(opts map[string]any) (core.Platform, error) {
	subscription, _ := opts["subscription"].(string)
	subscription = strings.TrimSpace(subscription)
	if subscription == "" {
		return nil, fmt.Errorf("googlechat: subscription is required (the Pub/Sub subscription your Chat app publishes to)")
	}
	projectID, err := projectFromSubscription(subscription)
	if err != nil {
		return nil, err
	}

	credentialsFile, _ := opts["credentials_file"].(string)
	credentialsFile = strings.TrimSpace(credentialsFile)
	if credentialsFile == "" {
		return nil, fmt.Errorf("googlechat: credentials_file is required (the Chat app's service-account key, used to pull events and send replies)")
	}
	keyBytes, err := os.ReadFile(credentialsFile)
	if err != nil {
		return nil, fmt.Errorf("googlechat: read credentials_file: %w", err)
	}
	conf, err := google.JWTConfigFromJSON(keyBytes,
		chatBotScope, "https://www.googleapis.com/auth/pubsub")
	if err != nil {
		return nil, fmt.Errorf("googlechat: parse service account credentials: %w", err)
	}
	botClient := conf.Client(context.Background())

	allowFrom, _ := opts["allow_from"].(string)

	core.CheckAllowFrom("googlechat", allowFrom)

	return &Platform{
		subscription:    subscription,

View on GitHub (pinned to 4000b2338a)

Solutions

Set credentials_file to the absolute path of the downloaded service-account JSON key, e.g. "/etc/cc-connect/chat-app-sa.json"
Create/download the key from Google Cloud IAM if it doesn't exist yet (Service Accounts → Keys → Add key → JSON)
Verify the config key spelling is exactly 'credentials_file' and the value survives env expansion
Ensure the file also passes the follow-up checks (readable, valid JSON, correct scopes) to avoid the next errors

Example fix

// before
[platforms.options]
subscription = "projects/p/subscriptions/chat-events"
// after
[platforms.options]
subscription = "projects/p/subscriptions/chat-events"
credentials_file = "/etc/cc-connect/chat-app-sa.json"

Defensive patterns

Strategy: validation

Validate before calling

// Go: pre-validate before constructing the platform
cred, _ := opts["credentials_file"].(string)
if strings.TrimSpace(cred) == "" {
    return errors.New("googlechat: credentials_file must be a non-empty path to the service-account JSON key")
}
if _, err := os.Stat(cred); err != nil {
    return fmt.Errorf("credentials_file not readable: %w", err)
}

Try / catch

p, err := core.CreatePlatform("googlechat", opts)
if err != nil && strings.Contains(err.Error(), "credentials_file is required") {
    return fmt.Errorf("config: add credentials_file = \"/path/to/sa.json\" to googlechat options: %w", err)
}

Prevention

Always pair subscription and credentials_file in googlechat config
Verify key file presence with a startup/doctor check
Store the path in one well-documented place (e.g. /etc/cc-connect/)
Template configs with explicit placeholders so missing values are obvious

When it happens

Trigger: googlechat.New invoked with opts where opts["credentials_file"] is missing, not a string, empty, or whitespace-only (subscription validation has already passed).

Common situations: Service-account key path never added to config.toml; wrong key name ('credentials', 'service_account'); value empty because an env var is unset; migrating config from another platform that uses api_key instead.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/0c05b703e33660d8. Report an issue: GitHub.