---
title: "Check a web app now and report what is wrong."
method: GET
path: "/WebApp/diagnose"
tags: ["WebApp", "Web Apps"]
---

# Check a web app now and report what is wrong.

`GET /WebApp/diagnose`

## Request

- Base URL: `https://cpanel-server.tld:2083/execute`
- URL: `https://cpanel-server.tld:2083/execute/WebApp/diagnose`
- Auth: HTTP basic

This function checks one web application now and reports what is
wrong with it, the evidence for that, and what would repair it.

This is the escalation path from `list`. `list` reports what the
scheduled health check last found, so it is at most one check
interval old; this function runs the check live.

It is read-only. It makes no start, stop, restart or redeploy call,
and it rewrites no reverse-proxy configuration, even when the
`action` it reports recommends one.

It records what it found as the application's `health`, so a
subsequent `list` reports this verdict rather than the older one. It
does not add to the application's incident history: that history is
the scheduled check's record of what it found, and this function can
be called at will.

## Query parameters

- `name` string, required

## Response `200`

HTTP Request was successful.

- object
  - `apiversion` integer: The version of the API.
  - `func` string: The name of the method called.
  - `module` string: The name of the module called.
  - `result` object
    - `data` object: What the check found.
      - `action` 'none' | 'restart' | 'rewire_proxy' | 'notify': What would repair the cause, which is not always a restart. This function does not carry it out. * `none` — Nothing should be done to the application. * `restart` — Restarting it is a reasonable repair. * `rewire_proxy` — Its reverse-proxy configuration needs rewriting. * `notify` — Only a person can resolve this.
      - `cause` 'healthy' | 'stopped_by_user' | 'deploying' | 'never_deployed' | 'out_of_memory' | 'crash_on_boot' | 'dead' | 'unit_missing' | 'wedged' | 'stale_proxy_port' | 'missing_include' | 'port_unreachable' | 'public_unreachable' | 'app_error' | 'unknown': What is wrong with the application. * `healthy` — Nothing. * `stopped_by_user` — You stopped it. * `deploying` — A deploy is in progress. * `never_deployed` — No deploy has ever succeeded. * `out_of_memory` — It exceeded its memory limit and was killed. * `crash_on_boot` — It has never started successfully since its last deploy. * `dead` — It ran and then stopped. * `unit_missing` — Its service definition is gone. * `wedged` — It is running but not answering on its port. * `stale_proxy_port` — Its reverse proxy points at a port it no longer uses. * `missing_include` — It has no reverse-proxy configuration. * `port_unreachable` — It is running but publishes no port. * `public_unreachable` — It answers locally, and its domain does not. * `app_error` — It answers requests with an error of its own. * `unknown` — Nothing could be read about it.
      - `checked_at` string, date-time: When this check ran, in ISO 8601 format.
      - `detail` object: What the cause needs to say to be specific, and nothing more. The keys depend on the `cause`: an `out_of_memory` verdict carries `peak_bytes`, `limit_bytes` and `oom_kills`, a `stale_proxy_port` carries the ports that disagree as `was` and `now`, and a healthy application carries nothing.
      - `domain` string, domain: The domain the application is bound to.
      - `evidence` object: What was observed, tier by tier, so an interface can show why the verdict is what it is. A tier that could not be read is `null` rather than empty: an unreadable signal is not the same as a signal that reported nothing.
        - `container` object, nullable: What the container runtime reports, or `null` if it could not be read.
          - `exit_code` integer, nullable: The exit code of the last run, or `null` while it is still running.
          - `host_port` integer, nullable: The port the container is published on, or `null` if it publishes none.
          - `oom_killed` boolean: Whether the last run was killed for exceeding its memory limit.
          - `state` string: The container's state.
        - `loopback` integer, nullable: Whether the application accepts a connection on its published port: `1` yes, `0` no, and `null` when there was no port to try. This is a connection, not a request: the question is whether the application's process is listening, so an API-only application that answers `404` at `/` is not reported as broken.
        - `memory` object, nullable: The application's own memory accounting, or `null` when neither a live figure nor a configured limit could be read.
          - `limit_bytes` integer, nullable: The memory limit, or `null` if it is not capped.
          - `oom_kills` integer: How many times a process was killed for exceeding the limit during this run.
          - `peak_bytes` integer, nullable: The highest memory use recorded during this run, or `null` once the run is over or if this server does not keep that figure.
        - `probe` object, nullable: The container runtime's own health probe, or `null` for an application whose container has none configured.
          - `log` object[]: The last few probe results, newest last.
          - `status` string: The probe's verdict. * `healthy` — The probe passes. * `unhealthy` — The probe fails. * `starting` — The application is still inside its start period, so the probe is not yet evidence of anything. * empty — The container has no health probe configured, which is the case for every application deployed before probes existed. This is not a fault.
        - `proxy` object: Two records of the same fact, compared rather than probed: the port the container is published on, and the port the web server was told to proxy to. They disagree after a restore, which no restart can fix.
          - `published_port` integer, nullable: The port the container is published on, or `null` if it publishes none.
          - `wired_port` integer, nullable: The port the reverse-proxy configuration names, `null` if there is no configuration for the domain or if it could not be read.
          - `wiring_known` 0 | 1: Whether the reverse-proxy configuration could be read at all. When this is `0`, `wired_port` means "not known" rather than "not configured", and no proxy verdict is reached.
        - `public` object, nullable: What a visitor to the application's URL gets, or `null` when the fetch was not made — it is only worth making once the local tiers are known good.
          - `error` string, nullable: Why the request never arrived, when it did not.
          - `ok` boolean: Whether the response was below `500`. An API-only application answering `404` at `/` is not a fault.
          - `responded` boolean: Whether an HTTP response came back at all. A request that never arrived is a DNS, TLS or virtual-host problem; one that arrived and was answered with an error is the application's own answer.
          - `status` integer, nullable: The HTTP status returned, or `null` if the request never arrived.
        - `three_way` 'ok' | 'app' | 'port' | 'domain' | 'unknown': Which side is broken, which is the value of this check: everything but `app` is a case restarting the application cannot fix. * `ok` — Every tier is fine, the public URL included. * `app` — The container itself is not answering. * `port` — The container is up and its published port is not usable. * `domain` — Both are fine and the public URL is not. * `unknown` — Not enough could be observed to say.
        - `unit` object, nullable: What the service manager reports, or `null` if it could not be read.
          - `active` string: The unit's active state.
          - `exit_status` integer, nullable: The exit status the unit last recorded.
          - `loaded` boolean: Whether the service manager has a definition for the unit at all. When it does not, the definition has to be regenerated, which is a redeploy.
          - `restarts` integer, nullable: How many times the service has been restarted, as the system's own retry counter reports it.
          - `result` string: The unit's last result.
          - `sub_state` string: The unit's detailed state.
      - `health` object, nullable: What the most recent health check found, or `null` if the application has not been checked yet. This is read from the last check rather than measured when you call this function, so it is at most one check interval old.
        - `action` 'none' | 'restart' | 'rewire_proxy' | 'notify': What would repair the cause, which is not always a restart. * `none` — Nothing should be done to the application. * `restart` — Restarting it is a reasonable repair. * `rewire_proxy` — Its reverse-proxy configuration needs rewriting. * `notify` — Only a person can resolve this.
        - `cause` 'healthy' | 'stopped_by_user' | 'deploying' | 'never_deployed' | 'out_of_memory' | 'crash_on_boot' | 'dead' | 'unit_missing' | 'wedged' | 'stale_proxy_port' | 'missing_include' | 'port_unreachable' | 'public_unreachable' | 'app_error' | 'unknown': What is wrong with the application. * `healthy` — Nothing. * `stopped_by_user` — You stopped it. * `deploying` — A deploy is in progress. * `never_deployed` — No deploy has ever succeeded. * `out_of_memory` — It exceeded its memory limit and was killed. * `crash_on_boot` — It has never started successfully since its last deploy. * `dead` — It ran and then stopped. * `unit_missing` — Its service definition is gone. * `wedged` — It is running but not answering on its port. * `stale_proxy_port` — Its reverse proxy points at a port it no longer uses. * `missing_include` — It has no reverse-proxy configuration. * `port_unreachable` — It is running but publishes no port. * `public_unreachable` — It answers locally, and its domain does not. * `app_error` — It answers requests with an error of its own. * `unknown` — Nothing could be read about it.
        - `checked_at` string, date-time: When the check ran, in ISO 8601 format.
        - `healthy_at` string, date-time, nullable: When the application was last seen healthy, in ISO 8601 format, or `null` if it never has been. An application that has not been healthy since its last deploy has never started successfully, which a restart cannot fix.
        - `incidents` integer: How many incidents were recorded for this application in the last 24 hours. Only the most recent incidents are kept, so this figure stops climbing once enough of them have been recorded to show the pattern.
        - `memory` object, nullable: The application's own memory accounting at the time of the check, or `null` when neither a live figure nor a configured limit could be read.
          - `limit_bytes` integer, nullable: The memory limit, or `null` if it is not capped.
          - `oom_kills` integer: How many times a process was killed for exceeding the limit during this run.
          - `peak_bytes` integer, nullable: The highest memory use recorded during this run, or `null` once the run is over or if this server does not keep that figure.
        - `oom_incidents` integer: How many of the last 24 hours' incidents were the application exceeding its memory limit, counted over the same kept incidents as `incidents`. Past a few of these, raising the limit is the only thing that will help, and that is your decision.
        - `restarts` integer: How many times the service has been restarted, as the system's own retry counter reports it. Omitted when that counter could not be read.
        - `state` 'healthy' | 'stopped' | 'pending' | 'recovering' | 'needs_attention' | 'unreachable' | 'unknown': A summary of `cause` suitable for a status badge. * `healthy` — Nothing is wrong. * `stopped` — You stopped it. * `pending` — It is deploying, or has never deployed. * `recovering` — Something is wrong and a repair is available. * `needs_attention` — Something is wrong that only you can resolve. * `unreachable` — The application is fine and its domain is not. * `unknown` — Nothing could be read about it.
      - `name` string: The application's name (slug).
      - `state` 'healthy' | 'stopped' | 'pending' | 'recovering' | 'needs_attention' | 'unreachable' | 'unknown': A summary of `cause` suitable for a status badge. * `healthy` — Nothing is wrong. * `stopped` — You stopped it. * `pending` — It is deploying, or has never deployed. * `recovering` — Something is wrong and a repair is available. * `needs_attention` — Something is wrong that only you can resolve. * `unreachable` — The application is fine and its domain is not. * `unknown` — Nothing could be read about it.
      - `url` string, url: The application's live HTTPS URL.
    - `errors` string[], nullable: List of errors if the API failed.
    - `messages` string[], nullable: List of messages generated by the API.
    - `metadata` object
    - `status` 0 | 1: - `1` - Success. - `0` - Failed. Check the `errors` field for more details.
    - `warnings` string[], nullable: List of warnings generated by the API. Warnings describe non-critical failures or other problematic conditions noted while running a API.

## Changes

- **2026-11-04** `05239220da37`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cpanel/apis/cpanel-uapi/changes/WebApp/diagnose/get.md)

---

[API](https://skmtc.dev/cpanel/apis/cpanel-uapi.md) - [All operations](https://skmtc.dev/cpanel/apis/cpanel-uapi/llms.txt) - [OpenAPI document](https://skmtc.dev/cpanel/apis/cpanel-uapi/revisions/05239220da37?raw)