# 22031 — invalid_argument_for_sql_json_datetime_function

> Source-backed reference for PostgreSQL SQLSTATE 22031.
---

# 22031

## At a glance {#at-a-glance}
A SQL/JSON datetime method received an invalid type, precision, or format. Fixed jsonpath execution reports an unrecognized format and hints to use a datetime template argument.

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| Field | Value |
| --- | --- |
| SQLSTATE | `22031` |
| Condition | `invalid_argument_for_sql_json_datetime_function` |
| Status | `active` |
| Known present by | `13.0` |
| Locked snapshots | `13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| Macros | `ERRCODE_INVALID_ARGUMENT_FOR_SQL_JSON_DATETIME_FUNCTION` |
| Aliases | `—` |

<!-- source facts: data/errcodes/22031.json -->
<!-- END SQLSTATE FACTS -->

## Messages {#messages}
The datetime-method guards use these primary texts:

| Guard | Primary and hint |
| --- | --- |
| non-string item | `jsonpath item method .%s() can only be applied to a string` |
| `.datetime()` format not recognized | `%s format is not recognized: "%s"`; HINT: `Use a datetime template argument to specify the input data format.` |
| precision outside integer range | `time precision of jsonpath item method .%s() is out of range for type integer` |
| invalid adjusted precision | `time precision of jsonpath item method .%s() is invalid` |

## Meaning {#meaning}
The fixed `executeDateTimeMethod` path first requires a scalar string. `.datetime(template)` passes the explicit template to `parse_datetime`: when `jspThrowErrors(cxt)` is false, its `ErrorSaveContext` turns a parse failure into `jperError`; when throwing is enabled, the parser receives no save context and may throw its underlying error. The no-template `.datetime()`, `.date()`, `.time()`, `.time_tz()`, `.timestamp()`, and `.timestamp_tz()` paths try their enumerated ISO formats, saving each candidate failure in `ErrorSaveContext` even on a throwing execution; only after every candidate fails does the final 22031 `RETURN_ERROR` branch decide whether to throw or return `jperError`. Optional time precision is converted to an integer and checked before adjustment. A missing format, incompatible conversion, non-string item, or invalid precision uses 22031.

## Diagnosis {#diagnosis}
Record the method name, input JSON item type, datetime text, template text if present, and precision argument. The `.datetime()` no-format match has the HINT to provide a template; the other methods use fixed ISO candidates and have no such template hint. Separate a scalar type mismatch from a format failure and from precision range/adjustment errors. `lax` controls structural auto-wrap/unwrap and structural-error handling; it does not generally suppress datetime parse or conversion errors. Check the executor's `throwErrors`/`RETURN_ERROR` path and the `jsonb_path_*` function's `silent` parameter or SQL/JSON ON ERROR clause to determine whether a saved parse error was returned or raised.

## Response {#response}
Pass a string item to the method, use a template matching the datetime text for `.datetime()`, or choose the method whose ISO type matches the input. Keep precision within the integer and datetime typmod rules. If a non-ERROR ON ERROR behavior intentionally handles parse failure, repair or retain that behavior according to the application contract; otherwise correct the input or template. If an ERROR occurred in an explicit transaction, roll back or roll back to the existing savepoint before retrying; autocommit can retry the corrected expression.

## Versions {#versions}
The locked catalogue records this condition from 13.0; the fixed SQL/JSON datetime source path here is PostgreSQL 18.6. No natural runtime observation is claimed for this page.

## Related {#related}
[`22007`](../22007/), [`22018`](../22018/)

## Sources {#sources}
The datetime method is [`src/backend/utils/adt/jsonpath_exec.c#L2326-2780`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L2326), including string/type checks, explicit-template and ISO candidate parsing, `ErrorSaveContext`, conversions, and precision guards. The strict/lax/throw split is defined by [`#L235-249`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L235) and [`#L654-727`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonpath_exec.c#L654). The structured [evidence record](../data/evidence/22031.json) retains the exact primary and hint roles; no natural runtime was run.