Debugging settings reference
Reference for the Debugging pages in Retool organization settings on self-hosted instances, including On prem environment, SSO debugging, and Services debugging.
The Debugging settings section contains read-only pages that report on the current state of a self-hosted Retool instance. These pages provide insight into the currently deployed configuration of an instance and can help admins troubleshoot issues.
Available debugging settings
Organization admins have access to the following debugging pages:
- On prem environment: All environment variable values currently configured.
- SSO: Access tokens for single sign-on.
- Services Debugging: The status of various critical services, such as code executor and the app builder.
The debugging pages and their content depend on your instance's configuration.
Environment variables
The On prem environment page reports on all environment variables configured for the instance. Any variable that's set with a custom value also includes its default value, rendered as (Default: "value").
To learn what each variable does, refer to the environment variables reference.
Environment variables that hold secret values don't display their value. They appear only as secret.
| Section | Contents |
|---|---|
| Environment Variable Settings | Variables set on the instance, with their values. Some variables include a short description. |
| Retool "Exposed" Variables | Custom variables you can use on resource pages. Values aren't shown. |
| Unset Variables | Variables Retool recognizes that aren't set on the instance. Some include a short description. |
| Unknown Variables | Variables set in the instance's environment that Retool doesn't use. Values aren't shown. Variables that start with npm_ are excluded. |
SSO debugging
The SSO debugging page reports on the access token and ID token for your currently authenticated session. Each token appears under a heading with the provider name.
The page shows tokens only when you signed in with Okta or a custom OAuth 2.0 provider. For any other sign-in method, including SAML and email and password, the page shows an empty Access Token block.
Don't share any information from this page. The tokens can be used to impersonate you in Retool.
For more information about configuring single sign-on, refer to the SSO documentation.
SSO test connection results
The SAML and custom OAuth 2.0 SSO settings each include a Test connection button. The button is disabled until you save your changes. Selecting it opens the sign-in flow in a new tab. When the sign-in completes, Retool shows a results page in that tab with the following sections.
| Section | Visible when | Contents |
|---|---|---|
| Connection Status | Always | A Test connection success banner that lists the first name, last name, and email Retool parsed from the response, or an Error banner with the error message if the sign-in failed. |
| Issues Detected | The test succeeded and either attributes are missing or the test would remove you from the admin group. | A warning that you would be removed from the Admin group, and a description of each attribute Retool couldn't find in the response, with the SSO setting to change. |
| Connection Details | Always. Collapsed by default. | The details listed in the following table. |
The success banner also reports how the test would affect your permission groups:
- Permission groups not configured to change: Role or group sync isn't configured for the SSO type.
- Permission groups will change from [a] to [b]: The groups that the response maps you to differ from your current groups.
- Permission groups remains the same: The groups match your current groups.
For custom OAuth 2.0, the banner also lists SSO Roles when a roles key is configured. For SAML, it lists SSO Groups when group claim sync or LDAP group sync is enabled.
Expand Connection Details to see the following information.
| Detail | Contents |
|---|---|
| Response from SSO Provider | The raw token response. Appears only when the provider returned one. |
| Decoded tokens | The decoded token contents. Appears only when the provider returned a token. |
| Parsed attributes | The first name, last name, email, roles, and groups Retool extracted from the response. |
| Dry run logs | Logs from the test sign-in. |
The raw and decoded tokens can contain sensitive information. Don't share them.
Services debugging
The Services debugging page reports on the health of the critical services that make up a self-hosted instance. These health checks run whenever you visit the page, ensuring that the displayed results are current.
Each section includes a Recheck Service button that reruns every check on the page. If a check fails in the Temporal, Workflows worker, Code executor, API, or Workflows backend sections, an Issue Detected banner appears at the top.
Failed checks include a link to the relevant documentation. For a description of each service, refer to the self-hosted architecture guide.
Temporal
Reports on the connection to Temporal. If the instance has no Temporal client, the section shows only Configured: No. For more information, refer to Temporal.
| Check | Reports |
|---|---|
| Using Retool Managed Temporal | Yes if the instance uses Retool-managed Temporal, otherwise No. |
| Namespace Egress | Whether the instance can reach the Temporal host and port. The default port is 7233. |
| Connectivity | Whether the instance can connect to Temporal. |
Workflows worker
Reports on the health of the service used to orchestrate workflows. This section appears only when the Temporal namespace egress check passes.
| Check | Reports |
|---|---|
| Worker Can Reach Temporal | Whether a test workflow ran on the worker. Reports Cannot Reach Worker on failure. |
| Worker Version | The worker version. A warning appears if it doesn't match the backend version. Appears after the worker test returns a result. |
| Worker Can Reach Code Executor | Whether the worker can reach the code executor. Appears after the worker test returns a result. |
| Potential Worker Collision | Appears only when another worker may be polling the same Temporal queue, which can cause non-deterministic workflow failures. |
Code executor
Reports on the state of the service that runs custom code. If the main backend can't reach the service, the section shows Service not reachable from main backend/API.
| Check | Reports |
|---|---|
| Status | OK if the code executor is found, otherwise Not Found. |
| Version | The code executor version. A warning appears if it doesn't match the backend version. Appears only when the code executor is found. |
| Supports Nsjail | Yes if the code executor supports nsjail sandboxing, otherwise No. Appears only when the code executor is found. |
| Built-in Packages Disabled | Yes if built-in packages are disabled in the code executor, otherwise No. Appears only when the code executor is found and the backend can read the setting. |
API (main backend)
Reports on whether the main backend can reach its dependencies.
| Check | Reports |
|---|---|
| Postgres Egress | Whether the backend can reach the platform database. |
| Temporal Namespace Egress | Whether the backend can reach the Temporal namespace. |
| Code Executor Egress | Whether the backend can reach the code executor. |
App builder
Reports on the services the app builder depends on. The checks run in the following order.
| Check | Reports |
|---|---|
| Feature Flags | Whether the feature flags the app builder requires are enabled on your license key. |
| JS Executor | Whether the JavaScript executor is reachable. |
| Workflow backend from JS Executor | Whether the JavaScript executor can reach the workflows backend. |
| Git Storage | Whether the backend can access the blob storage bucket for Git data. |
| Snapshot Storage | Whether the backend can access the blob storage bucket for snapshots. |
| Agent Sandbox - Controller | Whether the agent sandbox controller is healthy. |
| Agent Sandbox - Proxy | Whether the agent sandbox proxy is healthy. |
The section also includes an Agent Sandbox - Start row with a Run Sandbox Test button. The test starts a real sandbox, so it doesn't run automatically. Select the button to run it. The button is disabled until the Controller and Proxy checks pass.
Workflows backend
Reports on whether the workflows backend can reach its dependencies. If the main backend can't reach the workflows backend, the section shows a single Status check with the error. Each of the following checks appears only if the workflows backend reports that dependency.
| Check | Reports |
|---|---|
| Postgres Egress | Whether the workflows backend can reach the platform database. |
| Temporal Namespace Egress | Whether the workflows backend can reach the Temporal namespace. |
| Code Executor Egress | Whether the workflows backend can reach the code executor. |
Job queues (pg-boss)
Reports on the status of the app builder's orchestration backend. For more information about choosing a backend, refer to Configure the app builder's orchestration backend.
| Check | Reports |
|---|---|
| Configuration | Whether app builder jobs run on Temporal or pg-boss. |
| Connections | Whether the worker and the sender are connected. |
| Agent Sandbox - Start | The result of the same sandbox test as in the App Builder section. |
| pg-boss - Job Test | Result of a no-op job sent through pg-boss. Runs when you select Run Job Test. The button is disabled when app builder jobs run on Temporal (Not available on Temporal). |
| Warnings | A log of warnings that pg-boss saved. |
The Warnings table has the columns Type, Message, Details, and Time. Use the Warning type selector to filter by type. The types are Slow Query, Queue Backlog, and Clock Skew.
MCP
Reports on the health of the Retool MCP server. This section appears only when the MCP server and its diagnostics are enabled on the instance. To enable the MCP server, refer to Enable the MCP server.
The section displays one of the following overall statuses:
| Status | Meaning |
|---|---|
No failed MCP checks | The MCP server reported health and no check failed. |
MCP checks need attention | The MCP server reported a problem, or at least one check or the Test tools/list test failed. |
MCP service not configured | The instance has no MCP service target. |
MCP health unavailable | The health request failed. Check that the MCP service is running. |
Recheck reruns the checks. Each check shows Passed, Failed, or Not checked, along with what was tested and where the test ran from.
| Check | Reports |
|---|---|
| Retool backend to MCP | Whether the Retool backend can reach the MCP /healthcheck endpoint over the internal service route. |
| MCP to Retool backend | Whether the MCP server can reach the Retool /api/checkHealth endpoint, using RETOOL_BACKEND_URL. |
| MCP to Git server | Whether the MCP server can reach the Git server /api/checkHealth endpoint, using RETOOL_GIT_SERVER_URL. |
| MCP to agent executor proxy | Whether the MCP server can reach the agent executor proxy /health endpoint. |
| Public challenge | Whether an unauthenticated request to the public /mcp endpoint returns a bearer challenge. |
| Public resource metadata | Whether the public OAuth protected resource metadata is reachable. |
| Public OAuth metadata | Whether the public OAuth authorization server metadata is reachable. |
| Shared-token access | Whether the MCP connectivity diagnostics endpoint accepts a shared token. |
The public checks run from the MCP pod to your instance's canonical URL. They don't prove that an external client can reach the instance.
The Test tools/list button runs an authenticated MCP initialize and tools/list request from the Retool backend. It uses an OAuth grant that you approve, scoped to MCP read access, and revokes the token after the check. When the test passes, the section lists the tools available to you.
The section also includes two expandable areas:
- Configured toolsets: The toolsets enabled on the server. To enable only specific toolsets, set
RETOOL_TOOLSETSon the MCP service to a comma-separated list, such asapps,resources,workflows. When unset, all toolsets are enabled. - Deployment connection settings: Whether
RETOOL_BACKEND_URLandAGENT_SANDBOX_PROXY_INGRESS_DOMAINare set. These variables are optional, so an unset value isn't necessarily a problem.