22030 — duplicate_json_object_key_value

A JSON object construction encountered a duplicate key. The fixed unique-key JSON builder and aggregate paths report duplicate JSON object key value: %s; JSONB finalization has a related variant.

English manual coverage begins with PostgreSQL 8.1. Source history and runtime observations have their own recorded version boundaries.

Reading PG 18·Select a recorded version

12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: Data Exception
condition name: duplicate_json_object_key_value
lang: en
sqlstate: 22030

Definition PG 18

22030

At a glance {#at-a-glance}

A JSON object construction encountered a duplicate key. The fixed unique-key JSON builder and aggregate paths report duplicate JSON object key value: %s; JSONB finalization has a related variant.

Messages {#messages}

The unique-key paths use these primary texts:

| Path | Primary | | --- | --- | | JSON builder or aggregate with unique keys | duplicate JSON object key value: %s | | JSONB object finalization or unique-key validation | duplicate JSON object key value |

Meaning {#meaning}

22030 is raised when a JSON object operation has explicitly enabled key uniqueness and sees the same key twice in one object. The JSON builders and object aggregates carry a unique_keys flag; their unique variants record keys and raise at insertion or object finalization. Ordinary json/jsonb input uses the flag as false, and ordinary builders or aggregates do not turn every duplicate in input text into 22030. Strict or absent-on-null variants omit NULL-valued fields from output, but the unique variants retain the key long enough to check it, so a duplicate key can still fail even when its value would be skipped. A NULL key itself is a separate argument error.

Diagnosis {#diagnosis}

Identify the constructor or aggregate and whether its documented form enforces unique keys. The %s primary names the duplicate key for the JSON builder/aggregate path; the JSONB finalization and validation path uses the shorter primary. Distinguish a duplicate-key policy from invalid JSON syntax, a NULL object key, or ordinary json/jsonb parsing that permits duplicate input under its normal semantics.

Response {#response}

Apply the owner’s duplicate-key policy: de-duplicate or aggregate upstream values when uniqueness is required, or use a documented non-unique operation only when retaining the operation’s duplicate-key semantics is intentional. Do not solve a NULL key or malformed JSON error by changing the uniqueness flag. If an ERROR occurred in an explicit transaction, roll back or roll back to the existing savepoint before retrying; autocommit can retry the corrected action.

Versions {#versions}

The locked catalogue records this condition from 12.0; the fixed JSON and JSONB source paths here are PostgreSQL 18.6. No natural runtime observation is claimed for this page.

Related {#related}

22032, 22023

Sources {#sources}

JSON unique-key builders and aggregates are src/backend/utils/adt/json.c#L1002-1127 and #L1224-1295; JSON uniqueness validation is #L1810-1853. JSONB ordinary input leaves uniqueness disabled in src/backend/utils/adt/jsonb.c#L74-102, while unique builders and finalization are #L1125-1163 and src/backend/utils/adt/jsonb_util.c#L1952-2005. The structured evidence record retains the unique-key and NULL-skipping boundaries; no natural runtime was run.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read fixed definition.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "22030 is duplicate_json_object_key_value in SQLSTATE Class 22."
}

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a natural runtime observation.",
  "method": "Read the complete unique-key builder, parser-validation, JSONB input, and final uniqueify paths.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0",
    "src.json.unique-builder",
    "src.json.unique-constructor",
    "src.json.unique-validate",
    "src.jsonb.unique-builder",
    "src.jsonb.input",
    "src.jsonb.uniqueify"
  ],
  "statement": "Fixed JSON and JSONB builders/aggregates enable uniqueness checks only for their unique-key variants; duplicate keys then raise 22030, while ordinary json/jsonb input leaves unique_keys false and does not use this guard. Strict/absent-on-null variants skip NULL-valued entries from output but retain their key long enough to enforce uniqueness when unique_keys is true."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue boundary.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 22030 from 12.0 without proving exact implementation introduction."
}

messages · message.0

{
  "limits": "",
  "message_id": "message.0",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.0",
    "primary_template": "duplicate JSON object key value: %s",
    "severity_source": "ERROR",
    "sources": [
      "src.path.0"
    ],
    "sqlstate": "22030"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.0"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "duplicate JSON object key value:",
      "position": 0,
      "role": "",
      "template": "duplicate JSON object key value: %s"
    }
  ]
}

messages · message.jsonb

{
  "limits": "",
  "message_id": "message.jsonb",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.jsonb",
    "primary_template": "duplicate JSON object key value",
    "severity_source": "ERROR",
    "sources": [
      "src.jsonb.uniqueify"
    ],
    "sqlstate": "22030"
  },
  "severity": "ERROR",
  "sources": [
    "src.jsonb.uniqueify"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "duplicate JSON object key value",
      "position": 0,
      "role": "",
      "template": "duplicate JSON object key value"
    }
  ]
}

messages · message.json-validate

{
  "limits": "",
  "message_id": "message.json-validate",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.json-validate",
    "primary_template": "duplicate JSON object key value",
    "severity_source": "ERROR",
    "sources": [
      "src.json.unique-validate"
    ],
    "sqlstate": "22030"
  },
  "severity": "ERROR",
  "sources": [
    "src.json.unique-validate"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "duplicate JSON object key value",
      "position": 0,
      "role": "",
      "template": "duplicate JSON object key value"
    }
  ]
}

sources · src.errcodes.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L215"
}

sources · src.path.0

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/json.c",
  "position": 1,
  "sha256": "9d0ed0ee9d5bac07990f2b413b48ba7dac2bff3b24797233fd887926a704c102",
  "source_id": "src.path.0",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/json.c#L1124"
}

sources · src.json.unique-builder

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/json.c",
  "position": 2,
  "sha256": "9d0ed0ee9d5bac07990f2b413b48ba7dac2bff3b24797233fd887926a704c102",
  "source_id": "src.json.unique-builder",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/json.c#L1002"
}

sources · src.json.unique-constructor

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/json.c",
  "position": 3,
  "sha256": "9d0ed0ee9d5bac07990f2b413b48ba7dac2bff3b24797233fd887926a704c102",
  "source_id": "src.json.unique-constructor",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/json.c#L1224"
}

sources · src.json.unique-validate

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/json.c",
  "position": 4,
  "sha256": "9d0ed0ee9d5bac07990f2b413b48ba7dac2bff3b24797233fd887926a704c102",
  "source_id": "src.json.unique-validate",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/json.c#L1810"
}

sources · src.jsonb.unique-builder

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/jsonb.c",
  "position": 5,
  "sha256": "b137e223a73a8a4287e9b3a4d7dedcb3a3a40bdd9d08c6e5c5fd998d4139ba3f",
  "source_id": "src.jsonb.unique-builder",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonb.c#L1125"
}

sources · src.jsonb.input

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/jsonb.c",
  "position": 6,
  "sha256": "b137e223a73a8a4287e9b3a4d7dedcb3a3a40bdd9d08c6e5c5fd998d4139ba3f",
  "source_id": "src.jsonb.input",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonb.c#L74"
}

sources · src.jsonb.uniqueify

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/jsonb_util.c",
  "position": 7,
  "sha256": "444230d5187605ae276d3197fab41033e530e2dcbd94721d900005c7a52eb7b0",
  "source_id": "src.jsonb.uniqueify",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/jsonb_util.c#L1952"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:78c0cba9e069ad8f0f295af9d5b5e0f34b26e97ed6847d6ad96b43a148c7d75b

Text language: en · english-manuals:78c0cba9e069ad8f0f295af9d5b5e0f34b26e97ed6847d6ad96b43a148c7d75b