apache/beam · error

table name missing components

Error message

table name missing components: %v

What it means

NewQualifiedTableName (sdks/go/pkg/beam/io/bigqueryio/bigquery.go) parses a BigQuery table name in "<project>:<dataset>.<table>" form. If the string lacks the required ':' separator or '.' separator, or the '.' appears before the ':', the format is considered unparseable and this error is returned with the original string.

Solutions

1. Rewrite the table reference as "project:dataset.table" (e.g. "my-proj:my_ds.my_table").
2. If you have separate project/dataset/table variables, format them with fmt.Sprintf("%s:%s.%s", project, dataset, table).
3. If you only have "project.dataset.table", split on '.' and rebuild with the colon before parsing.
4. Use the wrapped mustParseTable only in tests; in production call NewQualifiedTableName and handle the error.

Example fix

// before
qtn, err := bigqueryio.NewQualifiedTableName("my-proj.my_dataset.my_table")
// after
qtn, err := bigqueryio.NewQualifiedTableName("my-proj:my_dataset.my_table")

var bqTableRe = regexp.MustCompile(`^[^:]+:[^.]+\.[^.]+$`)
if !bqTableRe.MatchString(tableRef) {
    return fmt.Errorf("table %q must be project:dataset.table", tableRef)
}

qtn, err := bigqueryio.NewQualifiedTableName(tableRef)
if err != nil {
    return fmt.Errorf("bad BigQuery table ref %q: %w", tableRef, err)
}

When it happens

Trigger: Calling NewQualifiedTableName (directly or via mustParseTable, e.g. through beamio.Read/Write BigQuery options) with a string like "mytable", "project.dataset" (no colon), "project:dataset" (no dot), or "dataset.table:project" (dot before colon).

Common situations: Users passing just a table name or a "project.dataset" DNN-style name instead of the colon-qualified legacy-style name the Beam BigQuery IO expects.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• table name has empty components
• bigqueryio.Query: failed to encode query parameters
• bigqueryio.queryFn: failed to decode query parameters
• Expected a table reference (PROJECT:DATASET.TABLE or…
• Failure parsing TableRow

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/bb2d1a116dc16550. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/io/bigqueryio/bigquery.go:76

	// Project is the Google Cloud project ID.
	Project string `json:"project"`
	// Dataset is the dataset ID within the project.
	Dataset string `json:"dataset"`
	// Table is the table ID within the dataset.
	Table string `json:"table"`
}

// String formats the qualified name as "<project>:<dataset>.<table>".
func (qn QualifiedTableName) String() string {
	return fmt.Sprintf("%v:%v.%v", qn.Project, qn.Dataset, qn.Table)
}

// NewQualifiedTableName parses "<project>:<dataset>.<table>" into a QualifiedTableName.
func NewQualifiedTableName(s string) (QualifiedTableName, error) {
	c := strings.LastIndex(s, ":")
	d := strings.LastIndex(s, ".")
	if c == -1 || d == -1 || d < c {
		return QualifiedTableName{}, errors.Errorf("table name missing components: %v", s)
	}

	project := s[:c]
	dataset := s[c+1 : d]
	table := s[d+1:]
	if strings.TrimSpace(project) == "" || strings.TrimSpace(dataset) == "" || strings.TrimSpace(table) == "" {
		return QualifiedTableName{}, errors.Errorf("table name has empty components: %v", s)
	}
	return QualifiedTableName{Project: project, Dataset: dataset, Table: table}, nil
}

// Read reads all rows from the given table. The table must have a schema
// compatible with the given type, t, and Read returns a PCollection<t>. If the
// table has more rows than t, then Read is implicitly a projection.
func Read(s beam.Scope, project, table string, t reflect.Type) beam.PCollection {
	mustParseTable(table)

	s = s.Scope("bigquery.Read")

View on GitHub (pinned to 12126d8942)