tailscale/tailscale · error

could not detect environment; provide --id-token explicitly

Error message

could not detect environment; provide --id-token explicitly

What it means

Raised by ObtainProviderToken when environment detection matched none of GitHub Actions, AWS IMDS, GCP metadata, ECS, or Azure. Workload identity federation cannot mint an ID token without knowing which provider to ask, so the user must supply the token via the --id-token flag. The condition is an unrecognized runtime environment.

Source

Thrown at wif/wif.go:56

// and then tries to obtain an ID token for the audience that is passed as an argument
// To detect the environment, we do it in the following intentional order:
//  1. GitHub Actions (strongest env signals; may run atop any cloud)
//  2. AWS via IMDSv2 token endpoint (does not require env vars)
//  3. GCP via metadata header semantics
//  4. AWS ECS via ECS token endpoint and env vars provided by ECS
//  5. Azure via metadata endpoint
func ObtainProviderToken(ctx context.Context, audience string) (string, error) {
	env := detectEnvironment(ctx)

	switch env {
	case EnvGitHub:
		return acquireGitHubActionsIDToken(ctx, audience)
	case EnvAWS:
		return acquireAWSWebIdentityToken(ctx, audience)
	case EnvGCP:
		return acquireGCPMetadataIDToken(ctx, audience)
	default:
		return "", errors.New("could not detect environment; provide --id-token explicitly")
	}
}

func detectEnvironment(ctx context.Context) Environment {
	if os.Getenv("ACTIONS_ID_TOKEN_REQUEST_URL") != "" &&
		os.Getenv("ACTIONS_ID_TOKEN_REQUEST_TOKEN") != "" {
		return EnvGitHub
	}

	client := httpClient()
	if detectAWSIMDSv2(ctx, client) {
		return EnvAWS
	}
	if detectGCPMetadata(ctx, client) {
		return EnvGCP
	}
	if os.Getenv("ECS_CONTAINER_METADATA_URI_V4") != "" {
		return EnvAWS

View on GitHub (pinned to 6e0912f979)

Solutions

1. Pass --id-token explicitly with a token from your identity provider
2. Run inside a supported environment with metadata endpoints reachable
3. Check network access to the metadata service

When it happens

Trigger: Thrown at wif/wif.go:56 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of tailscale/tailscale@6e0912f979 (2026-08-18). Data as JSON: /api/errors/9535be17743de2f4. Report an issue: GitHub.