Skip to main content

Debugging settings reference

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.
Debugging pages and settings availability

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.

Best practice

Environment variables that hold secret values don't display their value. They appear only as secret.

SectionContents
Environment Variable SettingsVariables set on the instance, with their values. Some variables include a short description.
Retool "Exposed" VariablesCustom variables you can use on resource pages. Values aren't shown.
Unset VariablesVariables Retool recognizes that aren't set on the instance. Some include a short description.
Unknown VariablesVariables 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.

Caution

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.

SectionVisible whenContents
Connection StatusAlwaysA 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 DetectedThe 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 DetailsAlways. 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.

DetailContents
Response from SSO ProviderThe raw token response. Appears only when the provider returned one.
Decoded tokensThe decoded token contents. Appears only when the provider returned a token.
Parsed attributesThe first name, last name, email, roles, and groups Retool extracted from the response.
Dry run logsLogs from the test sign-in.
Caution

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.

CheckReports
Using Retool Managed TemporalYes if the instance uses Retool-managed Temporal, otherwise No.
Namespace EgressWhether the instance can reach the Temporal host and port. The default port is 7233.
ConnectivityWhether 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.

CheckReports
Worker Can Reach TemporalWhether a test workflow ran on the worker. Reports Cannot Reach Worker on failure.
Worker VersionThe 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 ExecutorWhether the worker can reach the code executor. Appears after the worker test returns a result.
Potential Worker CollisionAppears 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.

CheckReports
StatusOK if the code executor is found, otherwise Not Found.
VersionThe code executor version. A warning appears if it doesn't match the backend version. Appears only when the code executor is found.
Supports NsjailYes if the code executor supports nsjail sandboxing, otherwise No. Appears only when the code executor is found.
Built-in Packages DisabledYes 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.

CheckReports
Postgres EgressWhether the backend can reach the platform database.
Temporal Namespace EgressWhether the backend can reach the Temporal namespace.
Code Executor EgressWhether 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.

CheckReports
Feature FlagsWhether the feature flags the app builder requires are enabled on your license key.
JS ExecutorWhether the JavaScript executor is reachable.
Workflow backend from JS ExecutorWhether the JavaScript executor can reach the workflows backend.
Git StorageWhether the backend can access the blob storage bucket for Git data.
Snapshot StorageWhether the backend can access the blob storage bucket for snapshots.
Agent Sandbox - ControllerWhether the agent sandbox controller is healthy.
Agent Sandbox - ProxyWhether 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.

CheckReports
Postgres EgressWhether the workflows backend can reach the platform database.
Temporal Namespace EgressWhether the workflows backend can reach the Temporal namespace.
Code Executor EgressWhether 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.

CheckReports
ConfigurationWhether app builder jobs run on Temporal or pg-boss.
ConnectionsWhether the worker and the sender are connected.
Agent Sandbox - StartThe result of the same sandbox test as in the App Builder section.
pg-boss - Job TestResult 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).
WarningsA 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:

StatusMeaning
No failed MCP checksThe MCP server reported health and no check failed.
MCP checks need attentionThe MCP server reported a problem, or at least one check or the Test tools/list test failed.
MCP service not configuredThe instance has no MCP service target.
MCP health unavailableThe 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.

CheckReports
Retool backend to MCPWhether the Retool backend can reach the MCP /healthcheck endpoint over the internal service route.
MCP to Retool backendWhether the MCP server can reach the Retool /api/checkHealth endpoint, using RETOOL_BACKEND_URL.
MCP to Git serverWhether the MCP server can reach the Git server /api/checkHealth endpoint, using RETOOL_GIT_SERVER_URL.
MCP to agent executor proxyWhether the MCP server can reach the agent executor proxy /health endpoint.
Public challengeWhether an unauthenticated request to the public /mcp endpoint returns a bearer challenge.
Public resource metadataWhether the public OAuth protected resource metadata is reachable.
Public OAuth metadataWhether the public OAuth authorization server metadata is reachable.
Shared-token accessWhether 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_TOOLSETS on the MCP service to a comma-separated list, such as apps,resources,workflows. When unset, all toolsets are enabled.
  • Deployment connection settings: Whether RETOOL_BACKEND_URL and AGENT_SANDBOX_PROXY_INGRESS_DOMAIN are set. These variables are optional, so an unset value isn't necessarily a problem.