What causes "urlTemplate is required" in grafana/k6?

Provide the template: --secret-source=url=urlTemplate=https://api.example.com/secrets/{key}

urlTemplate is required

Error message

urlTemplate is required

What it means

Returned by the URL secret source (validateURLTemplate) when the consolidated config has an empty urlTemplate. The URL secret source builds requests from a template with a {key} placeholder (e.g. https://api.example.com/secrets/{key}); without a template it cannot form any request, so construction fails with the sentinel error errMissingURLTemplate.

Source

Thrown at internal/secretsource/url/url.go:30

	"math/rand" // nosemgrep: math-random-used // This is being used for retry jitter
	"net/http"
	"net/url"
	"strings"
	"time"

	"github.com/sirupsen/logrus"
	"github.com/tidwall/gjson"
	"gopkg.in/guregu/null.v3"

	"go.k6.io/k6/v2/lib"
	"go.k6.io/k6/v2/lib/fsext"
	"go.k6.io/k6/v2/lib/types"
	"go.k6.io/k6/v2/secretsource"
	"golang.org/x/time/rate"
)

var (
	errMissingURLTemplate = errors.New("urlTemplate is required")
	errFailedToGetSecret  = errors.New("failed to get secret")
)

// extConfig holds the configuration for URL-based secrets.
type extConfig struct {
	// URLTemplate is a URL template with {key} placeholder
	// Example: "https://api.example.com/secrets/{key}"
	URLTemplate string `json:"urlTemplate"`

	// Headers to include in the request (e.g., Authorization headers)
	Headers map[string]string `json:"headers"`

	// Method is the HTTP method to use (default: GET)
	Method null.String `json:"method"`

	// ResponsePath is a JSON path to extract the secret value from the response
	// Use dot notation for nested fields (e.g., "data.value")
	// If empty, the entire response body is treated as the secret

View on GitHub (pinned to 93accf6570)

Solutions

Provide the template: --secret-source=url=urlTemplate=https://api.example.com/secrets/{key}
Or set it in the JSON config: {"urlTemplate": "https://api.example.com/secrets/{key}"}
Ensure the template contains the {key} placeholder (a follow-up validation rejects templates without it)

Example fix

# before
k6 run --secret-source=url=header.AUTHORIZATION=Bearer
token script.js
# urlTemplate omitted -> urlTemplate is required

# after
k6 run --secret-source=url=urlTemplate=https://api.example.com/secrets/{key},header.AUTHORIZATION="Bearer $TOKEN" script.js

Defensive patterns

Strategy: validation

Validate before calling

# Require a template containing {key} before registering the url secret source:
case "${TEMPLATE:-}" in
  ""|*[!{key}]*) echo "urlTemplate is required and must contain {key}"; exit 1;;
esac
k6 run --secret-source=url=urlTemplate="$TEMPLATE" script.js

Prevention

Always pass urlTemplate as the first parameter when registering the url secret source
Keep a validated example config in the repo and CI-lint it (template present, contains {key}, URL parses)
Do not ship commented-out template lines in examples; readers copy them verbatim

When it happens

Trigger: Registering the url secret source via --secret-source=url=... without a urlTemplate parameter; a JSON config file for the source that omits urlTemplate; K6_SECRET_SOURCE_URL_URL_TEMPLATE exported as empty; passing only headers (e.g. Authorization) but no template.

Common situations: First-time setup of HTTP-backed secrets where the user wires auth but forgets the template; config files copied from examples that comment out the template line; templating systems that drop the value when the backing variable is undefined.

Related errors

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