grafana/k6 · error · errTagEmptyName

invalid tag, empty name

Error message

invalid tag, empty name

What it means

parseTagNameValue rejects --tag values whose '=' is the first character (idx == 0), i.e. the tag name is empty. CLI tag arguments must be name=value pairs; an empty name has nothing to attach the metric tag to, so option parsing fails before the test starts.

Source

Thrown at internal/cmd/options.go:18

package cmd

import (
	"errors"
	"fmt"
	"strings"

	"github.com/spf13/pflag"
	"gopkg.in/guregu/null.v3"

	"go.k6.io/k6/v2/internal/build"
	"go.k6.io/k6/v2/lib"
	"go.k6.io/k6/v2/lib/types"
	"go.k6.io/k6/v2/metrics"
)

var (
	errTagEmptyName   = errors.New("invalid tag, empty name")
	errTagEmptyValue  = errors.New("invalid tag, empty value")
	errTagEmptyString = errors.New("invalid tag, empty string")
)

func optionFlagSet() *pflag.FlagSet {
	flags := pflag.NewFlagSet("", 0)
	flags.SortFlags = false

	flags.Int64P("vus", "u", 1, "number of virtual users")
	flags.DurationP("duration", "d", 0, "test duration limit")
	flags.Int64P("iterations", "i", 0, "script total iteration limit (among all VUs)")
	flags.StringSliceP("stage", "s", nil, "add a `stage`, as `[duration]:[target]`")
	flags.String("execution-segment", "", "limit execution to the specified segment, e.g. 10%, 1/3, 0.2:2/3")
	flags.String("execution-segment-sequence", "", "the execution segment sequence") // TODO better description
	flags.BoolP("paused", "p", false, "start the test in a paused state")
	flags.Bool("no-setup", false, "don't run setup()")
	flags.Bool("no-teardown", false, "don't run teardown()")
	flags.Int64("max-redirects", 10, "follow at most n redirects")

View on GitHub (pinned to 93accf6570)

Solutions

1. Give the tag a name: use --tag "env=prod" syntax (name=value)
2. If the tag comes from variables, assert the name part is non-empty before building the argument
3. Check K6_TAGS entries too — each entry must contain a non-empty name before the '='

Example fix

# before
k6 run --tag "=prod" script.js   # ERR: invalid tag, empty name

# after
k6 run --tag "env=prod" script.js

# validate every tag argument before invoking k6
for t in "${TAGS[@]}"; do
  case "$t" in
    ""|"="*|""*[=]*) ;;
  esac
done
# simpler guard: name=${t%%=*}; [ -n "$name" ] || { echo "bad tag: $t"; exit 1; }

When it happens

Trigger: Running with --tag "=somevalue" (or K6_TAGS="=somevalue" / --tag "=a=b" variants where the name portion before the first '=' is empty). The switch on the index of '=' hits case 0 and returns this error.

Common situations: Shell variable meant to hold the tag name being empty and interpolated as "$NAME=value" -> "=value"; scripts concatenating tag parts without validating the name; copy-paste from docs dropping the name.

Related errors

• invalid tag, empty value
• stack value is required but it was not passed or is empty
• 104
• the --local-execution flag is not compatible with the --exit
• the --local-execution flag is not compatible with the --show

AI-assisted analysis of grafana/k6@93accf6570 (2026-08-15). Data as JSON: /api/errors/5b9227f78e935f76. Report an issue: GitHub.