39P01 — trigger_protocol_violated

39P01 is triggerprotocolviolated. Fixed PostgreSQL 18.6 paths cover the core trigger manager, contrib/tcn checks, and PL/Perl trigger return handling, with path-specific messages and severity.

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

8.1 8.2 8.3 8.4 9.0 9.1 9.2 9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: External Routine Invocation Exception
condition name: trigger_protocol_violated
lang: en
sqlstate: 39P01

Definition PG 18

39P01

At a glance {#at-a-glance}

39P01 is trigger_protocol_violated. Fixed PostgreSQL 18.6 paths cover the core trigger manager, contrib/tcn checks, and PL/Perl trigger return handling, with path-specific messages and severity.

Meaning {#meaning}

The code marks a trigger protocol mismatch. Core trigger-manager messages include trigger function %u returned null value and BEFORE STATEMENT trigger cannot return a value. contrib/tcn checks trigger timing, level, argument count, and primary-key setup; PL/Perl has a DELETE-row WARNING and a separate ERROR for an invalid trigger return.

Diagnosis {#diagnosis}

Use the exact message to identify the path. For the trigger manager, check the isnull flag and BEFORE STATEMENT return contract; for tcn, check AFTER timing, row level, argument count, and primary key; for PL/Perl, check whether the return is undef, SKIP, or MODIFY. The DELETE-row WARNING means a modification was ignored, while the invalid-return message is an ERROR.

Response {#response}

Correct the timing, level, event, arguments, or return value for the identified path. For PL/Perl, decide whether the ignored DELETE-row modification is acceptable before writing again; retry only after the contract is fixed and the original operation is known not to have completed.

Versions {#versions}

The locked catalogue records this condition from 7.4 in the listed formal snapshots and 19beta3; fixed source coverage is PostgreSQL 18.6.

Related {#related}

39P02, 39P03, 2F005

Sources {#sources}

See the fixed trigger.c, tcn.c, and plperl.c paths alongside the structured evidence record.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read the fixed definition row.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "39P01 is trigger_protocol_violated in Class 39."
}

claims · core-trigger

{
  "claim_id": "core-trigger",
  "limits": "",
  "method": "Read each fixed trigger-manager context and its message.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.trigger"
  ],
  "statement": "The core trigger manager reports this code when a trigger function sets the isnull flag, and for invalid BEFORE STATEMENT return values."
}

claims · tcn-contract

{
  "claim_id": "tcn-contract",
  "limits": "",
  "method": "Read the complete tcn checks around each report.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.path.tcn"
  ],
  "statement": "contrib/tcn checks trigger invocation context, AFTER timing, row level, argument count, and primary-key setup with this code."
}

claims · language-severity

{
  "claim_id": "language-severity",
  "limits": "",
  "method": "Compare ereport levels and exact messages.",
  "position": 3,
  "runtime": [],
  "sources": [
    "src.path.plperl"
  ],
  "statement": "PL/Perl has a WARNING variant for an ignored DELETE-row modification and an ERROR variant for an invalid trigger return value."
}

messages · message.trigger-null

{
  "limits": "",
  "message_id": "message.trigger-null",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.trigger-null",
    "primary_template": "trigger function %u returned null value",
    "severity_source": "ERROR",
    "sources": [
      "src.path.trigger"
    ],
    "sqlstate": "39P01"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.trigger"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "trigger function returned null value",
      "position": 0,
      "role": "",
      "template": "trigger function %u returned null value"
    }
  ]
}

messages · message.before-statement

{
  "limits": "",
  "message_id": "message.before-statement",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.before-statement",
    "primary_template": "BEFORE STATEMENT trigger cannot return a value",
    "severity_source": "ERROR",
    "sources": [
      "src.path.trigger"
    ],
    "sqlstate": "39P01"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.trigger"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "BEFORE STATEMENT trigger cannot return a value",
      "position": 0,
      "role": "",
      "template": "BEFORE STATEMENT trigger cannot return a value"
    }
  ]
}

messages · message.tcn-called-as-trigger

{
  "limits": "",
  "message_id": "message.tcn-called-as-trigger",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.tcn-called-as-trigger",
    "primary_template": "triggered_change_notification: must be called as trigger",
    "severity_source": "ERROR",
    "sources": [
      "src.path.tcn"
    ],
    "sqlstate": "39P01"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.tcn"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "triggered_change_notification: must be called as trigger",
      "position": 0,
      "role": "",
      "template": "triggered_change_notification: must be called as trigger"
    }
  ]
}

messages · message.tcn-after-change

{
  "limits": "",
  "message_id": "message.tcn-after-change",
  "path": "",
  "position": 3,
  "raw": {
    "id": "message.tcn-after-change",
    "primary_template": "triggered_change_notification: must be called after the change",
    "severity_source": "ERROR",
    "sources": [
      "src.path.tcn"
    ],
    "sqlstate": "39P01"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.tcn"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "triggered_change_notification: must be called after the change",
      "position": 0,
      "role": "",
      "template": "triggered_change_notification: must be called after the change"
    }
  ]
}

messages · message.tcn-each-row

{
  "limits": "",
  "message_id": "message.tcn-each-row",
  "path": "",
  "position": 4,
  "raw": {
    "id": "message.tcn-each-row",
    "primary_template": "triggered_change_notification: must be called for each row",
    "severity_source": "ERROR",
    "sources": [
      "src.path.tcn"
    ],
    "sqlstate": "39P01"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.tcn"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "triggered_change_notification: must be called for each row",
      "position": 0,
      "role": "",
      "template": "triggered_change_notification: must be called for each row"
    }
  ]
}

messages · message.tcn-one-parameter

{
  "limits": "",
  "message_id": "message.tcn-one-parameter",
  "path": "",
  "position": 5,
  "raw": {
    "id": "message.tcn-one-parameter",
    "primary_template": "triggered_change_notification: must not be called with more than one parameter",
    "severity_source": "ERROR",
    "sources": [
      "src.path.tcn"
    ],
    "sqlstate": "39P01"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.tcn"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "triggered_change_notification: must not be called with more than one parameter",
      "position": 0,
      "role": "",
      "template": "triggered_change_notification: must not be called with more than one parameter"
    }
  ]
}

messages · message.tcn-primary-key

{
  "limits": "",
  "message_id": "message.tcn-primary-key",
  "path": "",
  "position": 6,
  "raw": {
    "id": "message.tcn-primary-key",
    "primary_template": "triggered_change_notification: must be called on a table with a primary key",
    "severity_source": "ERROR",
    "sources": [
      "src.path.tcn"
    ],
    "sqlstate": "39P01"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.tcn"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "triggered_change_notification: must be called on a table with a primary key",
      "position": 0,
      "role": "",
      "template": "triggered_change_notification: must be called on a table with a primary key"
    }
  ]
}

messages · message.plperl-delete-warning

{
  "limits": "",
  "message_id": "message.plperl-delete-warning",
  "path": "",
  "position": 7,
  "raw": {
    "id": "message.plperl-delete-warning",
    "primary_template": "ignoring modified row in DELETE trigger",
    "severity_source": "WARNING",
    "sources": [
      "src.path.plperl"
    ],
    "sqlstate": "39P01"
  },
  "severity": "WARNING",
  "sources": [
    "src.path.plperl"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "ignoring modified row in DELETE trigger",
      "position": 0,
      "role": "",
      "template": "ignoring modified row in DELETE trigger"
    }
  ]
}

messages · message.plperl-invalid-return

{
  "limits": "",
  "message_id": "message.plperl-invalid-return",
  "path": "",
  "position": 8,
  "raw": {
    "id": "message.plperl-invalid-return",
    "primary_template": "result of PL/Perl trigger function must be undef, \"SKIP\", or \"MODIFY\"",
    "severity_source": "ERROR",
    "sources": [
      "src.path.plperl"
    ],
    "sqlstate": "39P01"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.plperl"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "result of PL/Perl trigger function must be undef, \"SKIP\", or \"MODIFY\"",
      "position": 0,
      "role": "",
      "template": "result of PL/Perl trigger function must be undef, \"SKIP\", or \"MODIFY\""
    }
  ]
}

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#L311"
}

sources · src.calls.REL_18_6

{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "raw/calls/REL_18_6.jsonl",
  "position": 1,
  "sha256": "9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf",
  "source_id": "src.calls.REL_18_6",
  "tag": "",
  "url": ""
}

sources · src.path.trigger

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/commands/trigger.c",
  "position": 2,
  "sha256": "0a539af85b0de1a04779f92202e7bfc77d85ae6da1747ea32527c67f39084fbd",
  "source_id": "src.path.trigger",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/commands/trigger.c#L2388-L2394"
}

sources · src.path.tcn

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "contrib/tcn/tcn.c",
  "position": 3,
  "sha256": "fd1b0dfa65a4b3f15bddc5ae6d4b71505e448a5febdaa20c5da8839d2b54350d",
  "source_id": "src.path.tcn",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/tcn/tcn.c#L77-L110"
}

sources · src.path.plperl

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/pl/plperl/plperl.c",
  "position": 4,
  "sha256": "90789190fd0bf5b53773b57b8c3287c88c35fbebdfa8310acab3f2d89910e4ba",
  "source_id": "src.path.plperl",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/pl/plperl/plperl.c#L2607-L2618"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:78c5cae4e0aa0c243deee6fbbaea42866d5af54907a6fc35db6b2e62bc1d0f3c

Text language: en · english-manuals:78c5cae4e0aa0c243deee6fbbaea42866d5af54907a6fc35db6b2e62bc1d0f3c