{"id":27615642,"url":"https://github.com/mikyll/apisix-plugin-error-page-advanced","last_synced_at":"2026-04-29T09:32:11.038Z","repository":{"id":288409985,"uuid":"964622346","full_name":"mikyll/apisix-plugin-error-page-advanced","owner":"mikyll","description":"Enhanced, custom implementation of the error-page Enterprise APISIX plugin.","archived":false,"fork":false,"pushed_at":"2025-04-17T10:43:15.000Z","size":21,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-07T09:44:02.279Z","etag":null,"topics":["api-gateway","apisix","lua","nginx","openresty","plugin"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikyll.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-11T14:07:21.000Z","updated_at":"2025-04-17T10:43:18.000Z","dependencies_parsed_at":"2025-04-23T03:57:06.171Z","dependency_job_id":null,"html_url":"https://github.com/mikyll/apisix-plugin-error-page-advanced","commit_stats":null,"previous_names":["mikyll/apisix-plugin-error-page-advanced"],"tags_count":0,"template":false,"template_full_name":"mikyll/apisix-plugin-template","purl":"pkg:github/mikyll/apisix-plugin-error-page-advanced","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikyll%2Fapisix-plugin-error-page-advanced","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikyll%2Fapisix-plugin-error-page-advanced/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikyll%2Fapisix-plugin-error-page-advanced/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikyll%2Fapisix-plugin-error-page-advanced/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikyll","download_url":"https://codeload.github.com/mikyll/apisix-plugin-error-page-advanced/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikyll%2Fapisix-plugin-error-page-advanced/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32419876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T06:29:02.080Z","status":"ssl_error","status_checked_at":"2026-04-29T06:29:00.631Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","apisix","lua","nginx","openresty","plugin"],"created_at":"2025-04-23T03:57:04.314Z","updated_at":"2026-04-29T09:32:11.032Z","avatar_url":"https://github.com/mikyll.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n[![APISIX][apisix-shield]][apisix-url]\n[![NGINX][nginx-shield]][nginx-url]\n[![Lua][lua-shield]][lua-url]\n[![Perl][perl-shield]][perl-url]\n[![YAML][yaml-shield]][yaml-url]\\\n[![Build Status][build-status-shield]][build-status-url]\n\n# APISIX Plugin error-page-advanced\n\nThis custom plugin allows APISIX to return a custom error page for each code. It allows extra customizations than [error-page](https://github.com/mikyll/apisix-plugin-error-page), such as any status code or request redirection.\n\n\u003c/div\u003e\n\n## Table of Contents\n\n- [APISIX Plugin error-page-advanced](#apisix-plugin-error-page-advanced)\n  - [Table of Contents](#table-of-contents)\n  - [Plugin Usage](#plugin-usage)\n    - [Installation](#installation)\n    - [Configuration](#configuration)\n      - [Plugin Metadata](#plugin-metadata)\n    - [Enable Plugin](#enable-plugin)\n      - [Traditional](#traditional)\n      - [Standalone](#standalone)\n    - [Example Usage](#example-usage)\n  - [Examples](#examples)\n    - [Standalone Example](#standalone-example)\n      - [Setup](#setup)\n      - [Test Routes](#test-routes)\n  - [Learn More](#learn-more)\n\n## Plugin Usage\n\n### Installation\n\nTo install custom plugins in APISIX there are 2 methods:\n\n- placing them alongside other built-in plugins, in `${APISIX_INSTALL_DIRECTORY}/apisix/plugins/` (by default `/usr/local/apisix/apisix/plugins/`);\n- placing them in a custom directory and setting `apisix.extra_lua_path` to point that directory, in `config.yaml`.\n\n[Back to TOC](#table-of-contents)\n\n### Configuration\n\nThis plugin can be configured for [Routes](https://apisix.apache.org/docs/apisix/terminology/route/) or [Global Rules](https://apisix.apache.org/docs/apisix/terminology/global-rule/).\n\n#### Plugin Metadata\n\n| Name                   | Type    | Required | Default | Valid values | Description                                                                                                                                                                                                               |\n| ---------------------- | ------- | -------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| enable                 | boolean | False    | `false` |              | If true, enable the plugin.                                                                                                                                                                                               |\n| set_content_length     | boolean | False    | `true`  |              | If true automatically set the Content-Length header. If set to false, removes the header.                                                                                                                                 |\n| error_XXX              | object  | False    |         |              | Error page to return when APISIX returns XXX status codes.                                                                                                                                                                |\n| error_XXX.body         | string  | False    |         |              | Response body. This can contain [NGiNX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html#variables). An extra variable `$status_text` is also available, which contains the message of the status code. |\n| error_XXX.content-type | string  | False    |         |              | Response content type.                                                                                                                                                                                                    |\n| error_XXX.redirect_url | string  | False    |         |              | URL to redirect the request to.                                                                                                                                                                                           |\n\n\u003e [!IMPORTANT]\n\u003e Plugin metadata set global values, shared accross all plugin instances. For example, if we have 2 different routes with `error-page-advanced` plugin enabled, `plugin_metadata` values will be the same for both of them.\n\n### Enable Plugin\n\nThe examples below enable `error-page-advanced` plugin globally. With these configurations, APISIX will return a custom error message for status codes `404` and `504`, on every route (even on undefined ones).\n\n#### Traditional\n\nConfigure the plugin metadata:\n\n```bash\ncurl http://127.0.0.1:9180/apisix/admin/plugin_metadata/error-page-advanced  -H \"X-API-KEY: $admin_key\" -X PUT -d '\n{\n  \"enable\": true,\n  \"error_404\": {\n    \"body\": \"{\\\"status_code\\\":$status,\\\"error\\\":\\\"$status_text\\\"}\",\n    \"content-type\": \"application/json\"\n  },\n  \"error_504\": {\n    \"redirect_url\": \"https://httpbin.org/get?foo=bar\"\n  },\n}'\n```\n\nEnable the plugin globally, using global rules:\n\n```bash\ncurl http://127.0.0.1:9180/apisix/admin/global_rules/error-page-advanced  -H \"X-API-KEY: $admin_key\" -X PUT -d '\n{\n  \"plugins\": {\n    \"error-page-advanced\": {}\n  }\n}'\n```\n\n#### Standalone\n\nConfigure the plugin metadata:\n\n```yaml\nplugin_metadata:\n  - id: error-page-advanced\n    enable: true\n    error_404:\n      body: |\n        {\n          \"status_code\": $status,\n          \"error\": \"$status_text\"\n        }\n      content-type: \"application/json\"\n    error_504:\n      redirect_url: \"https://httpbin.org/get?foo=bar\"\n```\n\nEnable the plugin globally, using global rules:\n\n```yaml\nglobal_rules:\n  - id: generic_error_page_advanced\n    plugins:\n      error-page-advanced: {}\n```\n\n### Example Usage\n\nSend some request to test error pages:\n\n- Route not defined (overrides default error page for 404):\n\n  ```bash\n  curl -iL \"localhost:9080/unknown\"\n  ```\n\n  Response:\n\n  ```bash\n  HTTP/1.1 404 Not Found\n  Content-Type: application/json\n  Connection: keep-alive\n  Server: APISIX/3.12.0\n  Content-Length: 49\n\n  {\n    \"status_code\": 404,\n    \"error\": \"Not Found\"\n  }\n  ```\n\n- Status code 504 returned from APISIX:\n  \n  ```bash\n  curl -iL \"localhost:9080/apisix_status/504\"\n  ```\n\n  Response:\n\n  ```bash\n  HTTP/1.1 302 Moved Temporarily\n  Content-Type: text/html\n  Content-Length: 239\n  Connection: keep-alive\n  Server: APISIX/3.11.0\n  Location: https://httpbin.org/get?foo=bar\n\n  HTTP/2 200 \n  content-type: application/json\n  content-length: 283\n  server: gunicorn/19.9.0\n  access-control-allow-origin: *\n  access-control-allow-credentials: true\n\n  {\n    \"args\": {\n      \"foo\": \"bar\"\n    }, \n    \"headers\": {\n      \"Accept\": \"*/*\", \n      \"Host\": \"httpbin.org\", \n      \"User-Agent\": \"curl/8.5.0\", \n      \"X-Amzn-Trace-Id\": \"Root=1-67fe8ffb-0368d480171b6ed602af7956\"\n    }, \n    \"origin\": \"X.X.X.X\", \n    \"url\": \"https://httpbin.org/get?foo=bar\"\n  }\n  ```\n\n[Back to TOC](#table-of-contents)\n\n## Examples\n\nFolder [`examples/`](examples/) contains a simple example that shows how to setup APISIX locally on Docker, and load `error-page-advanced` plugin.\n\nFor more example ideas, have a look at [github.com/mikyll/apisix-examples](https://github.com/mikyll/apisix-examples).\n\n[Back to TOC](#table-of-contents)\n\n### Standalone Example\n\n#### Setup\n\nSee [`apisix.yaml`](examples/apisix-docker-standalone/conf/apisix.yaml).\n\nRun the following command to setup the example:\n\n```bash\ndocker compose -f examples/apisix-docker-standalone/compose.yaml up\n```\n\n#### Test Routes\n\nRun [`test_routes.sh`](examples/utils/test_routes.sh) to send testing requests.\n\n[Back to TOC](#table-of-contents)\n\n## Learn More\n\n- [APISIX Source Code](https://github.com/apache/apisix)\n- [APISIX Deployment Modes](https://apisix.apache.org/docs/apisix/deployment-modes/)\n- [Developing custom APISIX plugins](https://apisix.apache.org/docs/apisix/plugin-develop)\n- [APISIX testing framework](https://apisix.apache.org/docs/apisix/internal/testing-framework)\n- [APISIX debug mode](https://apisix.apache.org/docs/apisix/debug-mode/)\n- [NGiNX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html#variables)\n- [APISIX Examples](https://github.com/mikyll/apisix-examples)\n\n\u003c!-- GitHub Shields --\u003e\n\n[apisix-shield]: https://custom-icon-badges.demolab.com/badge/APISIX-grey.svg?logo=apisix_logo\n[apisix-url]: https://apisix.apache.org/\n[nginx-shield]: https://img.shields.io/badge/Nginx-%23009639.svg?logo=nginx\n[nginx-url]: https://nginx.org/en/\n[lua-shield]: https://img.shields.io/badge/Lua-%232C2D72.svg?logo=lua\u0026logoColor=white\n[lua-url]: https://www.lua.org/\n[perl-shield]: https://img.shields.io/badge/Perl-%2339457E.svg?logo=perl\u0026logoColor=white\n[perl-url]: https://www.perl.org/\n[yaml-shield]: https://img.shields.io/badge/YAML-%23ffffff.svg?logo=yaml\u0026logoColor=151515\n[yaml-url]: https://yaml.org/\n[build-status-shield]: https://github.com/mikyll/apisix-plugin-error-page-advanced/actions/workflows/ci.yml/badge.svg\n[build-status-url]: https://github.com/mikyll/apisix-plugin-error-page-advanced/actions","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikyll%2Fapisix-plugin-error-page-advanced","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikyll%2Fapisix-plugin-error-page-advanced","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikyll%2Fapisix-plugin-error-page-advanced/lists"}