grafana/k6 · error

urlTemplate must be an absolute URL with a scheme (e.g., htt

Error message

urlTemplate must be an absolute URL with a scheme (e.g., https://...)

What it means

After substituting a dummy value for '{key}', k6 parses the template with url.Parse() and requires a non-empty Scheme. A template that parses successfully but has no scheme (a relative URL such as 'vault.example.com/{key}') cannot be fetched by the HTTP client, so validateURLTemplate() rejects it. Note that url.Parse rarely returns an error, so this scheme check is the main guard against non-absolute templates.

Source

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

	if urlTemplate == "" {
		return errMissingURLTemplate
	}

	// Require {key} placeholder to differentiate between secrets
	if !strings.Contains(urlTemplate, "{key}") {
		return errors.New("urlTemplate must contain {key} placeholder")
	}

	// Replace {key} placeholder with a dummy value for validation
	testURL := strings.ReplaceAll(urlTemplate, "{key}", "test")
	parsedURL, err := url.Parse(testURL)
	if err != nil {
		return fmt.Errorf("urlTemplate is not a valid URL: %w", err)
	}

	// Require absolute URL with scheme
	if parsedURL.Scheme == "" {
		return errors.New("urlTemplate must be an absolute URL with a scheme (e.g., https://...)")
	}

	return nil
}

func getConfig(arg string, fs fsext.Fs, env map[string]string) (extConfig, error) {
	// Start with defaults
	config := newConfig()

	// Apply environment variables
	// Order of precedence (lowest to highest):
	// 1. Defaults
	// 2. Environment variables
	// 3. Config file (if specified)
	// 4. Inline CLI flags
	envCfg, err := parseEnvConfig(env)
	if err != nil {
		return extConfig{}, err

View on GitHub (pinned to 93accf6570)

Solutions

1. Prefix the template with a scheme: 'https://vault.example.com/secrets/{key}'
2. If building the template from variables, assert it matches /^https?:\/\// before starting k6
3. Check for typos like 'httpss://' or a leading space that breaks scheme parsing

Example fix

# before
K6_SECRET_SOURCE_URL_URL_TEMPLATE='vault.example.com/secrets/{key}'

# after
K6_SECRET_SOURCE_URL_URL_TEMPLATE='https://vault.example.com/secrets/{key}'

const tpl = process.env.K6_SECRET_SOURCE_URL_URL_TEMPLATE ?? '';
if (!/^https?:\/\/.*\{key\}/.test(tpl)) {
  throw new Error(`bad urlTemplate: ${tpl}`);
}

When it happens

Trigger: Setting urlTemplate to a host/path without a protocol, e.g. 'vault.example.com/secrets/{key}' or '/secrets/{key}', via env var, inline arg, or JSON config file.

Common situations: Omitting the 'https://' prefix by accident; using a template built from a host variable where the scheme was expected to be implicit; copy-pasting a path-only endpoint from API docs.

Related errors

• urlTemplate must contain {key} placeholder
• timeout must be greater than 0
• requestsPerMinuteLimit must be greater than 0
• requestsBurst must be greater than 0
• maxRetries must be non-negative

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