Invalid variable path %q in namespace %s: cannot start with

Error message

Invalid variable path %q in namespace %s: cannot start with a leading '/'`

What it means

Returned by acl.Parse in acl/policy.go:601 when a variables path spec begins with '/'. Variables path specs are relative key prefixes (e.g. "secret/app") and must not start with a leading slash; the trailing backtick in the message is a literal typo in the source. The offending PathSpec and namespace name are included.

Source

Thrown at acl/policy.go:601

		// add to any existing capabilities
		if ns.Policy != "" {
			extraCap := expandNamespacePolicy(ns.Policy)
			ns.Capabilities = append(ns.Capabilities, extraCap...)
		}

		// Expand implicit capabilities
		expandNamespaceCapabilities(ns)

		if ns.Variables != nil {
			if len(ns.Variables.Paths) == 0 {
				return nil, fmt.Errorf("Invalid variable policy: no variable paths in namespace %s", ns.Name)
			}
			for _, pathPolicy := range ns.Variables.Paths {
				if pathPolicy.PathSpec == "" {
					return nil, fmt.Errorf("Invalid missing variable path in namespace %s", ns.Name)
				}
				if strings.HasPrefix(pathPolicy.PathSpec, "/") {
					return nil, fmt.Errorf(
						"Invalid variable path %q in namespace %s: cannot start with a leading '/'`",
						pathPolicy.PathSpec, ns.Name)
				}
				for _, cap := range pathPolicy.Capabilities {
					if !isPathCapabilityValid(cap) {
						return nil, fmt.Errorf(
							"Invalid variable capability '%s' in namespace %s", cap, ns.Name)
					}
				}
				pathPolicy.Capabilities = expandVariablesCapabilities(pathPolicy.Capabilities)

			}
		}

		// Remove the namespace name from the extra key list.
		p.removeExtraKey(ns.Name)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

Strip the leading '/' from the path spec, e.g. "/secret/app" → "secret/app"
Use strings.TrimPrefix(spec, "/") when building paths programmatically
Review wildcard rules: path specs are prefix/relative patterns, not absolute paths

Example fix

// before
variables {
  path "/secret/app" {
    capabilities = ["read"]
  }
}
// after
variables {
  path "secret/app" {
    capabilities = ["read"]
  }
}

Defensive patterns

Strategy: validation

Validate before calling

for _, ns := range policy.Namespaces {
    if ns.Variables == nil { continue }
    for _, p := range ns.Variables.Paths {
        if strings.HasPrefix(p.PathSpec, "/") {
            return fmt.Errorf("namespace %s: path %q must not start with '/'", ns.Name, p.PathSpec)
        }
    }
}

Type guard

func isRelativeVarPath(spec string) bool { return spec != "" && !strings.HasPrefix(spec, "/") }

Prevention

Treat variables path specs as relative prefixes, never absolute paths
Use strings.TrimPrefix(spec, "/") when accepting user-supplied paths
Document the no-leading-slash rule wherever users enter variable paths

When it happens

Trigger: Calling acl.Parse with a variables path like "/secret/app" or "/" inside a variables stanza — common when users write absolute-looking paths.

Common situations: Users familiar with absolute filesystem or Consul paths prefixing '/'; scripts joining path fragments with path.Join or string concatenation that yields a leading slash; migrating KV path configs from other systems.

Related errors

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/b81321b83d85ac58. Report an issue: GitHub.