{"record":{"id":"f0ca33d98b9efc87","repo":"mikefarah/yq","slug":"must-provide-a-date-time-format-string-and-an-expr","errorCode":null,"errorMessage":"must provide a date time format string and an expression, e.g. with_dtf(\"Monday, 02-Jan-06 at 3:04PM MST\"; <exp>)","messagePattern":"must provide a date time format string and an expression, e\\.g\\. with_dtf\\(\"Monday, 02-Jan-06 at 3:04PM MST\"; <exp>\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/yqlib/operator_datetime.go","lineNumber":33,"sourceCode":"\t\treturn \"\", err\n\t} else if result.MatchingNodes.Len() == 0 {\n\t\treturn \"\", fmt.Errorf(\"could not find %v for format_time\", parameterName)\n\t}\n\n\treturn result.MatchingNodes.Front().Value.(*CandidateNode).Value, nil\n}\n\nfunc withDateTimeFormat(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {\n\tif expressionNode.RHS.Operation.OperationType == blockOpType || expressionNode.RHS.Operation.OperationType == unionOpType {\n\t\tlayout, err := getStringParameter(\"layout\", d, context, expressionNode.RHS.LHS)\n\t\tif err != nil {\n\t\t\treturn Context{}, fmt.Errorf(\"could not get date time format: %w\", err)\n\t\t}\n\t\tcontext.SetDateTimeLayout(layout)\n\t\treturn d.GetMatchingNodes(context, expressionNode.RHS.RHS)\n\n\t}\n\treturn Context{}, errors.New(`must provide a date time format string and an expression, e.g. with_dtf(\"Monday, 02-Jan-06 at 3:04PM MST\"; <exp>)`)\n\n}\n\n// for unit tests\nvar Now = time.Now\n\nfunc nowOp(_ *dataTreeNavigator, context Context, _ *ExpressionNode) (Context, error) {\n\n\tnode := &CandidateNode{\n\t\tTag:   \"!!timestamp\",\n\t\tKind:  ScalarNode,\n\t\tValue: Now().Format(time.RFC3339),\n\t}\n\n\treturn context.SingleChildContext(node), nil\n\n}\n","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/mikefarah/yq/blob/8b5af0694bb82b41d4ae180fac9972029066f90a/pkg/yqlib/operator_datetime.go#L15-L51","documentation":"The `with_dtf` operator sets a date/time layout used by datetime functions in the following expression. It requires its RHS to be a block or union: LHS is the Go time layout string, RHS the expression. If the RHS is neither, the operator cannot extract a layout/argument pair and throws this usage error.","triggerScenarios":"Calling with_dtf with a single argument or non-block RHS, e.g. `yq 'with_dtf(\"2006-01-02\")'`, `yq 'with_dtf(.date)'`, or missing the `;` separator: `yq 'with_dtf(\"Mon Jan 2\"; .date)'` written as `with_dtf(\"Mon Jan 2\", .date)` with wrong syntax.","commonSituations":"Forgetting the semicolon separating the format string from the expression; passing a variable instead of a literal layout string as first arg; copying jq-style datetime syntax that yq doesn't share.","solutions":["Use the documented two-part form: with_dtf(\"Monday, 02-Jan-06 at 3:04PM MST\"; <expression>) with a literal Go layout string and a `;`.","Ensure the whole expression is quoted so shell/CLI parsing doesn't split it, leaving with_dtf with only one argument.","Verify the layout string is a Go reference-time layout (e.g. \"2006-01-02\"), not strftime/PHP format specifiers."],"exampleFix":"// before\nyq 'with_dtf(\"2006-01-02\")' file.yaml\n// after\nyq 'with_dtf(\"2006-01-02\"; .createdAt)' file.yaml","handlingStrategy":"validation","validationCode":"// before running with_dtf, ensure the two-part form:\n// with_dtf(\"<go layout>\"; <expression>)\n// e.g. shell check:\n// case \"$expr\" in with_dtf*\";\"*) ;; *) echo \"missing ';' separator\" >&2; exit 1;; esac","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always include the semicolon between the layout string and the expression.","Use Go reference-time layouts (2006-01-02), never strftime/%-style specifiers.","Quote the entire expression so the CLI receives it as one argument."],"tags":["datetime","expression","usage"],"backgroundTag":"invalid-operator-argument","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"}