apache/beam · error

table name has empty components

Error message

table name has empty components: %v

What it means

After splitting "<project>:<dataset>.<table>", NewQualifiedTableName checks that none of the three components is empty or whitespace-only; if any is, it returns "table name has empty components" with the original string. The separators exist but the name still has blank project, dataset, or table parts.

Solutions

1. Fill in the missing project, dataset, or table component at the reported position.
2. strings.TrimSpace the input before parsing and reject empty config values earlier.
3. Log the raw string from the error and validate the format with a regex like ^[^:]+:[^.]+\.[^.]+$ at config load time.
4. Set defaults for unset project/dataset variables before constructing the name.

Example fix

// before
table := cfg.Dataset + "." + cfg.Table // project empty
qtn, _ := bigqueryio.NewQualifiedTableName(":" + table)
// after
if cfg.Project == "" || cfg.Dataset == "" || cfg.Table == "" {
    return errors.New("project, dataset and table must all be set")
}
qtn, err := bigqueryio.NewQualifiedTableName(fmt.Sprintf("%s:%s.%s", cfg.Project, cfg.Dataset, cfg.Table))

parts := strings.SplitN(strings.TrimSpace(ref), ":", 2)
if len(parts) != 2 || strings.TrimSpace(parts[0]) == "" {
    return fmt.Errorf("project component empty in %q", ref)
}

qtn, err := bigqueryio.NewQualifiedTableName(ref)
if err != nil && strings.Contains(err.Error(), "empty components") {
    return fmt.Errorf("fill in missing project/dataset/table in %q", ref)
}

When it happens

Trigger: Passing strings like ":dataset.table", "project:.table", "project:dataset.", or strings with only whitespace in one segment to NewQualifiedTableName.

Common situations: Template/variable interpolation leaving empty placeholders (e.g. fmt.Sprintf("%s:%s.%s", p, d, t) with an unset variable), or trailing/leading whitespace around config values.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• table name missing components
• BigQuery %1$s not found for table "%2$s" . Please create…
• bigqueryio.Query: failed to encode query parameters
• bigqueryio.queryFn: failed to decode query parameters
• buffer_sec must be >= 0, got

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

Appendix: source

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

// 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")

	stmt := constructSelectStatement(t, bigQueryTag, table)

	return query(s, project, stmt, t)
}

func constructSelectStatement(t reflect.Type, tagKey string, table string) string {

View on GitHub (pinned to 12126d8942)