must provide a date time format string and an expression, e.

Error message

must provide a date time format string and an expression, e.g. with_dtf("Monday, 02-Jan-06 at 3:04PM MST"; <exp>)

What it means

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.

Source

Thrown at pkg/yqlib/operator_datetime.go:33

		return "", err
	} else if result.MatchingNodes.Len() == 0 {
		return "", fmt.Errorf("could not find %v for format_time", parameterName)
	}

	return result.MatchingNodes.Front().Value.(*CandidateNode).Value, nil
}

func withDateTimeFormat(d *dataTreeNavigator, context Context, expressionNode *ExpressionNode) (Context, error) {
	if expressionNode.RHS.Operation.OperationType == blockOpType || expressionNode.RHS.Operation.OperationType == unionOpType {
		layout, err := getStringParameter("layout", d, context, expressionNode.RHS.LHS)
		if err != nil {
			return Context{}, fmt.Errorf("could not get date time format: %w", err)
		}
		context.SetDateTimeLayout(layout)
		return d.GetMatchingNodes(context, expressionNode.RHS.RHS)

	}
	return 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>)`)

}

// for unit tests
var Now = time.Now

func nowOp(_ *dataTreeNavigator, context Context, _ *ExpressionNode) (Context, error) {

	node := &CandidateNode{
		Tag:   "!!timestamp",
		Kind:  ScalarNode,
		Value: Now().Format(time.RFC3339),
	}

	return context.SingleChildContext(node), nil

}

View on GitHub (pinned to 8b5af0694b)

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.

Example fix

// before
yq 'with_dtf("2006-01-02")' file.yaml
// after
yq 'with_dtf("2006-01-02"; .createdAt)' file.yaml

Defensive patterns

Strategy: validation

Validate before calling

// before running with_dtf, ensure the two-part form:
// with_dtf("<go layout>"; <expression>)
// e.g. shell check:
// case "$expr" in with_dtf*";"*) ;; *) echo "missing ';' separator" >&2; exit 1;; esac

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of mikefarah/yq@8b5af0694b (2026-09-05). Data as JSON: /api/errors/f0ca33d98b9efc87. Report an issue: GitHub.