invalid allowedDataset format: %q, expected 'project.dataset

Error message

invalid allowedDataset format: %q, expected 'project.dataset' or 'dataset'

What it means

Each entry in allowedDatasets must be either a bare 'dataset' name or a fully qualified 'project.dataset' (exactly one dot, two parts). Initialize parses each entry; any other format — multiple dots, empty segments, or unexpected characters — fails with this error.

Source

Thrown at internal/sources/bigquery/bigquery.go:228

			s.AuthTokenHeaderName = r.UseClientOAuth
		}
		// use client OAuth
		baseClientCreator, err := newBigQueryClientCreator(ctx, tracer, r.Project, r.Location, r.QuotaProject, r.Name, endpoint)
		if err != nil {
			return nil, fmt.Errorf("error constructing client creator: %w", err)
		}
		setupClientCaching(s, baseClientCreator)
	}

	allowedDatasets := make(map[string]struct{})
	// Get full id of allowed datasets and verify they exist.
	if len(r.AllowedDatasets) > 0 {
		for _, allowed := range r.AllowedDatasets {
			var projectID, datasetID, allowedFullID string
			if strings.Contains(allowed, ".") {
				parts := strings.Split(allowed, ".")
				if len(parts) != 2 {
					return nil, fmt.Errorf("invalid allowedDataset format: %q, expected 'project.dataset' or 'dataset'", allowed)
				}
				projectID = parts[0]
				datasetID = parts[1]
				allowedFullID = allowed
			} else {
				projectID = r.Project
				datasetID = allowed
				allowedFullID = fmt.Sprintf("%s.%s", projectID, datasetID)
			}

			if s.Client != nil {
				dataset := s.Client.DatasetInProject(projectID, datasetID)
				_, err := dataset.Metadata(ctx)
				if err != nil {
					s.Client.Close()
					if gerr, ok := err.(*googleapi.Error); ok && gerr.Code == http.StatusNotFound {
						return nil, fmt.Errorf("allowedDataset '%s' not found in project '%s'", datasetID, projectID)
					}

View on GitHub (pinned to 8cc6e09de2)

Solutions

Use exactly 'project.dataset' (one dot) or just 'dataset' for the source's own project.
Convert table-level IDs by dropping the table part (project.dataset.table -> project.dataset).
Remove empty or malformed entries from the allowedDatasets list.

Example fix

// before
allowedDatasets:
  - myproject.mydataset.mytable
// after
allowedDatasets:
  - myproject.mydataset

Defensive patterns

Strategy: validation

Validate before calling

func validateAllowedDatasets(entries []string) error {
	for _, e := range entries {
		if e == "" { return fmt.Errorf("empty allowedDataset entry") }
		parts := strings.Split(e, ".")
		if len(parts) > 2 || parts[0] == "" || (len(parts) == 2 && parts[1] == "") {
			return fmt.Errorf("invalid allowedDataset %q: use 'project.dataset' or 'dataset'", e)
		}
	}
	return nil
}

Try / catch

src, err := sourceRegistry.Initialize(ctx, cfg)
if err != nil {
	if strings.Contains(err.Error(), "invalid allowedDataset format") {
		return fmt.Errorf("fix allowedDatasets syntax: %w", err)
	}
	return err
}

Prevention

Never paste table IDs (project.dataset.table) into allowedDatasets.
Sanity-check each entry has at most one dot and no empty segments.
Keep dataset references in one canonical form (prefer fully qualified project.dataset).

When it happens

Trigger: allowedDatasets containing an entry like 'proj.ds.with.dots', 'project.', '.dataset', or an empty string with a dot producing wrong part counts.

Common situations: Copy-pasting fully qualified table IDs (project.dataset.table) instead of dataset IDs; trailing dots from sloppy editing; assuming nested or comma-separated formats are supported.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/54a7e36a03f81235. Report an issue: GitHub.