---
title: "corestack_error_pages_update"
url: https://docs.corefinity.com/mcp/tools/corestack_error_pages_update
type: tool
last_updated: 2026-11-13
feature: error-pages
related:
  - https://docs.corefinity.com/api/reference/site-settings/replace-site-error-pages.md
  - https://docs.corefinity.com/guides/sites/site-settings/error-and-maintenance-pages.md
---
# corestack_error_pages_update

**Change an environment's error pages.** Changes an environment's error pages (version from corestack_error_pages_get): per code the error page or the app's response, page HTML and messages, support email. Left out stays. 503 also governs deploy and platform maintenance. Scope: write. Long-running: answers with a task.

- Scope: `write`
- Runs as a task: yes

## When to use it

Change an environment's error and maintenance pages, with the `version` that `corestack_error_pages_get` answered. Check any new HTML with `corestack_error_pages_validate` (or `corestack_error_pages_preview`) first.

Send only what changes; everything you leave out keeps its current value:

- `codes`: for 404, 500, 502, 503 and 504, `page` shows the error page (ours, or your HTML) in place of the app's response, with the status code unchanged; `app` lets the app's own response through. When nginx itself has to answer (PHP not running gives 502, a request over 300 seconds gives 504) there is no app response: `page` shows the error page and `app` shows nginx's plain page.
- `503` also decides what happens during deploys and platform maintenance: `page` shows the maintenance page, `app` lets requests reach the app. The Maintenance switch in the Control Panel and a full stop by Corefinity support always show the maintenance page, whatever this setting.
- `pages`: for `maintenance`, `404`, `500`, `502`, `503` and `504`, `source` is your HTML and CSS (null puts the platform's page back) and `message` is the `{{message}}` text (null puts the default back).
- `support_email`: the `{{support_email}}` address; null clears it.

Pages are HTML and CSS only. The save removes anything a page may not hold (scripts, event handlers, links that are not `https:`, `mailto:` or images, iframes, forms) and keeps the page without it. When the app answers an API request (paths such as `/rest/`, `/graphql`, `/wp-json/`, or a request asking for JSON), its response always passes through; an error the web server answers itself on such a request (PHP not running, a request over 300 seconds) follows the settings.

The save is checked, written to the site and verified. The answer is a task on its `error_pages_change` operation (follow it with `corestack_site_operation_get`). The finished task's result carries `error_pages`: `outcome` is `applied` (the new pages are live and the site confirmed them), `applied_unverified` (live, but the site could not confirm them), `rejected` (the site refused the change and kept its previous pages; the task fails) or `unknown` (not known yet; it is checked again shortly). `applied` is true while the new pages are live, `verified` when the site confirmed them.

A change equal to the current pages answers `{operation: null, revision: null}`. After `rejected` or `unknown`, `retry: true` with the version applies the current pages again. 20 changes a minute for each environment, whoever sends them.

## Inputs

- `site_id` (integer, ≥ 1, required): the environment row.
- `version` (integer, ≥ 0, required): the version from `corestack_error_pages_get`; a newer change makes it stale.
- `codes` (object): `404`, `500`, `502`, `503`, `504`, each `page` or `app`.
- `pages` (object): `maintenance`, `404`, `500`, `502`, `503`, `504`, each `{source?, message?}`; source at most 64 KiB, message at most 300 characters, either null for the default.
- `support_email` (string or null): an email address.
- `note` (string, at most 200 characters): why, shown in the history.
- `retry` (boolean): true applies the current pages again after `rejected` or `unknown`. Send it with `version` and nothing to change.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "codes": {
      "additionalProperties": false,
      "description": "page: the error page; app: the app's response.",
      "properties": {
        "404": {
          "enum": [
            "page",
            "app"
          ],
          "type": "string"
        },
        "500": {
          "enum": [
            "page",
            "app"
          ],
          "type": "string"
        },
        "502": {
          "enum": [
            "page",
            "app"
          ],
          "type": "string"
        },
        "503": {
          "enum": [
            "page",
            "app"
          ],
          "type": "string"
        },
        "504": {
          "enum": [
            "page",
            "app"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "note": {
      "description": "Shown in the history.",
      "maxLength": 200,
      "type": "string"
    },
    "pages": {
      "additionalProperties": false,
      "description": "HTML and CSS (no JavaScript) and message per page; null: the default.",
      "properties": {
        "404": {
          "additionalProperties": false,
          "properties": {
            "message": {
              "type": [
                "string",
                "null"
              ]
            },
            "source": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "type": "object"
        },
        "500": {
          "additionalProperties": false,
          "properties": {
            "message": {
              "type": [
                "string",
                "null"
              ]
            },
            "source": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "type": "object"
        },
        "502": {
          "additionalProperties": false,
          "properties": {
            "message": {
              "type": [
                "string",
                "null"
              ]
            },
            "source": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "type": "object"
        },
        "503": {
          "additionalProperties": false,
          "properties": {
            "message": {
              "type": [
                "string",
                "null"
              ]
            },
            "source": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "type": "object"
        },
        "504": {
          "additionalProperties": false,
          "properties": {
            "message": {
              "type": [
                "string",
                "null"
              ]
            },
            "source": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "type": "object"
        },
        "maintenance": {
          "additionalProperties": false,
          "properties": {
            "message": {
              "type": [
                "string",
                "null"
              ]
            },
            "source": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "type": "object"
        }
      },
      "type": "object"
    },
    "retry": {
      "description": "Apply the current pages again after a rejected or unknown outcome.",
      "type": "boolean"
    },
    "site_id": {
      "minimum": 1,
      "type": "integer"
    },
    "support_email": {
      "description": "null clears it.",
      "maxLength": 254,
      "type": [
        "string",
        "null"
      ]
    },
    "version": {
      "description": "From corestack_error_pages_get.",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "site_id",
    "version"
  ],
  "type": "object"
}
```

## Refusals

- `stale`: someone changed the pages since `version` was read. Read them again with `corestack_error_pages_get`.
- `error_pages_locked`: Corefinity has locked this environment's error pages.
- `invalid_page`: a page has an error the save cannot fix; nothing was saved. `details.diagnostics` lists each with its page, line and column.
- `overlap_nginx_rules`: the environment's nginx rules already set an error page for that code. Set the code to `app`, or remove the `error_page` line from the nginx rules first.
- `too_large`: a page is over 64 KiB, or all pages together over 256 KiB.
- `runtime_lacks_capability`: the environment gets error pages with its next platform update.
- `operation_in_progress`: a change is still being applied; try again when it ends.
- `switch_reconcile_failed`: the Maintenance switch could not be brought in line first; nothing was changed. Try again.
- `managed_elsewhere`: another control panel manages this environment.
- `feature_off`: error pages are not available to you yet.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corestack_error_pages_update",
  "arguments": {
    "site_id": 4211,
    "version": 3,
    "codes": {
      "503": "app"
    },
    "note": "Show the shop's own holding page"
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_error_pages_update with site_id 4211, version 3, codes {"503":"app"}, note Show the shop's own holding page. (Change an environment's error pages.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [PUT /api/corestack/sites/{site}/error-pages](https://docs.corefinity.com/api/reference/site-settings/replace-site-error-pages.md)
- Guide: [Error pages](https://docs.corefinity.com/guides/sites/site-settings/error-and-maintenance-pages.md)
