{"record":{"id":"a50b6535d79086c7","repo":"mikefarah/yq","slug":"cannot-encode-v-as-uri-can-only-operate-on-strin-a50b65","errorCode":null,"errorMessage":"cannot encode %v as URI, can only operate on strings. Please first pipe through another encoding operator to convert the value to a string","messagePattern":"cannot encode (.+?) as URI, can only operate on strings\\. Please first pipe through another encoding operator to convert the value to a string","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/encoder_uri.go","lineNumber":32,"sourceCode":"func NewUriEncoder() Encoder {\n\treturn &uriEncoder{}\n}\n\nfunc (e *uriEncoder) CanHandleAliases() bool {\n\treturn false\n}\n\nfunc (e *uriEncoder) PrintDocumentSeparator(_ io.Writer) error {\n\treturn nil\n}\n\nfunc (e *uriEncoder) PrintLeadingContent(_ io.Writer, _ string) error {\n\treturn nil\n}\n\nfunc (e *uriEncoder) Encode(writer io.Writer, node *CandidateNode) error {\n\tif node.guessTagFromCustomType() != \"!!str\" {\n\t\treturn fmt.Errorf(\"cannot encode %v as URI, can only operate on strings. Please first pipe through another encoding operator to convert the value to a string\", node.Tag)\n\t}\n\t_, err := writer.Write([]byte(url.QueryEscape(node.Value)))\n\treturn err\n}\n","sourceCodeStart":14,"sourceCodeEnd":37,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/encoder_uri.go#L14-L37","documentation":"The URI encoder (@uri / ur operation) only accepts string nodes. If the node's tag is not !!str, it refuses to encode, telling you to convert the value to a string first (e.g. with string interpolation or the string operator). This prevents silently encoding numbers/booleans/objects in surprising ways.","triggerScenarios":"Running `yq '@uri' 123` or `yq '.val | @uri'` where .val is a number, boolean, null, or a map/sequence — any node whose guessed tag is not !!str.","commonSituations":"Querying numeric config values (ports, ids) and trying to URI-encode them; forgetting that YAML parses bare tokens as numbers/booleans (e.g. `version: 1.20` becomes a float); encoding entire objects instead of scalar string fields.","solutions":["Force string conversion before encoding: `yq '.val | tostring | @uri'` or pipe through string interpolation `\\\"\\(.val)\\\"`.","Quote the value in the source YAML so it parses as a string (`version: \\\"1.20\\\"`).","Select a string field instead of the whole map: `yq '.name | @uri'`.","For numbers, format explicitly: `yq '.port | format_int(10) | @uri'`."],"exampleFix":"// before\nyq '.port | @uri' config.yaml      # error: !!int\n// after\nyq '.port | tostring | @uri' config.yaml","handlingStrategy":"type-guard","validationCode":"yq '.val | tag' in.yaml  # must print \"!!str\" before @uri","typeGuard":"// shell pre-check\n[ \"$(yq '.val | tag' in.yaml)\" = \"!!str\" ] || echo \"needs tostring\"","tryCatchPattern":"// Go\nif err := uriEnc.Encode(w, node); err != nil {\n    if strings.Contains(err.Error(), \"can only operate on strings\") {\n        // convert node to !!str (tostring / interpolation) and retry\n    }\n}","preventionTips":["Always pipe through `tostring` before @uri unless the value is quoted","Quote YAML values like version numbers so they stay strings","Check `tag` output when debugging URI encoding"],"tags":["uri","encoder","type-mismatch","string-conversion"],"backgroundTag":"encoder-requires-string","analyzedSha":"8b5af0694bb82b41d4ae180fac9972029066f90a","analyzedAt":"2026-09-05T10:57:22.766Z","contentChangedAt":"2026-09-05T10:57:22.766Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}