Troubleshooting self-managed instances

Diagnose and resolve common issues with self-managed Retool deployments.

Use this page to diagnose and resolve common issues with self-managed Retool deployments.

Where do I start when something is broken?

Start with the broadest check and narrow down. Each step below narrows the problem to a smaller set of services.

1. Check the health endpoint. GET /api/checkHealth on the api service reports whether Retool considers itself healthy. It requires no authentication, and returns 500 with a NOT_HEALTHY status when a dependency check fails.
2. Check pod status. A pod stuck in CrashLoopBackOff failed during startup, which is usually a configuration problem rather than a runtime one. Jump to Why won't the api service start?.
3. Read the container logs. Retool logs the specific check that failed. Refer to Container logs for how to access them per deployment type.
4. Compare against the architecture. Confirm every service your configuration expects is actually running. Refer to Architecture for what each service does and which ones are optional.

Applying configuration changes

When a fix on this page changes an environment variable, it takes effect only once you apply the change the way your deployment applies configuration.

• Terraform blueprints. Set the value in retool_helm_extra_values in main.tf and run terraform apply. Editing Helm values directly on a blueprint-managed instance is overwritten by the next apply.
• Helm. Set the value in your values.yaml and run helm upgrade. That command restarts the affected pods as part of applying the new values, so restarting pods on their own leaves them running the old configuration.
• Docker Compose. Set the value in docker.env and run sudo docker compose up -d.

The rest of this page says "apply the change" to mean whichever of these your deployment uses.

Why won't the api service start?

The api service validates its configuration before it accepts traffic, and exits rather than starting in a broken state. The specific message names the check that failed.

Failed to start up due to configuration issues

Retool validated the environment and found one or more variables missing or malformed. The full message lists each problem as Failed to start up due to configuration issues. Errors: <list>.

Fix the named variables and apply the change. Refer to the environment variables reference for expected formats.

Code executor not detected

Retool checks that the code-executor service is reachable before starting, and exits when it isn't. The message is Could not detect healthy Code Executor. To ignore failures of this check on startup, set IGNORE_CODE_EXECUTOR_STARTUP_CHECK=true.

Check these in order:

1. The code-executor pod is running and healthy.
2. CODE_EXECUTOR_INGRESS_DOMAIN includes the protocol. A value without http:// or https:// logs CODE_EXECUTOR_INGRESS_DOMAIN is not set to a valid URL, include protocol (http:// or https://).
3. The api service can reach that address on your cluster network.

Setting IGNORE_CODE_EXECUTOR_STARTUP_CHECK=true lets the api service start anyway. Use it to get an instance back up while you investigate, not as a permanent setting. Python and JavaScript blocks in workflows fail without a working code-executor.

Why do queries fail with a database connection error?

Retool's own platform database backs the entire instance. When it's unreachable, the health check reports Database connection timed out. after five seconds.

1. Confirm the database is running and accepting connections.
2. Confirm the connection details in your deployment configuration are correct, including host, port, database name, and credentials.
3. Confirm network policies or security groups allow the api service to reach the database.
4. Check whether the connection pool is exhausted rather than the database being down. Under load, every connection can be in use while the database itself is healthy. Refer to Scale Retool infrastructure.

This is Retool's own database, not a resource you've connected. For failures querying a resource you added, refer to Troubleshooting resource connections.

Why do Python and JavaScript blocks fail in workflows?

Both run in the code-executor service. When it's unhealthy, Retool reports Code executor (<host>) not healthy or unreachable.

A second failure is a version mismatch. Retool requires code-executor to run the same version as the rest of the instance, and reports Code executor (<host>) version is <x>, expected <y> when it doesn't. This happens when an upgrade moves some services but not all of them. Re-apply the upgrade so every service lands on the same version together.

You can check the service directly at GET /api/workflows/serviceHealth/checkCodeExecutorServiceHealth.

Why don't workflows run at all?

Workflows depend on the workflows-backend service and on Temporal. Check them in that order.

• The workflows-backend service: A missing configuration reports Missing required environment variable WORKFLOW_BACKEND_HOST. A malformed one logs WORKFLOW_BACKEND_HOST is not set to a valid URL, include protocol (http:// or https://). Check the service directly at GET /api/workflows/serviceHealth/checkWorkflowBackendServiceHealth.
• Temporal: Retool uses Temporal to schedule and orchestrate workflow runs. Workflows queue without ever executing when the Temporal namespace is unreachable, which looks like a stuck workflow rather than an error. Refer to Temporal for the connection requirements.

If workflows execute but individual blocks fail, the problem is in the block rather than the infrastructure. Refer to Troubleshooting workflows.

Why isn't multiplayer editing working?

Multiplayer runs over a WebSocket connection that your proxy has to route separately from ordinary HTTP traffic. Repeated connection attempts in the browser's Network tab almost always mean the proxy isn't forwarding them.

To confirm traffic is reaching the multiplayer service, check its logs for messages such as Handle updated request for <url> and Handle new connection for <uuid>. No logs at all usually means the routing is wrong and traffic went to the api service instead.

Refer to Multiplayer editing for the required proxy configuration.

Why does Retool fail to start after I changed a secret?

When you load secrets from the file system, Retool validates each path at startup and exits if one is wrong:

Error	Resolution
RETOOL-CONFIG: Error setting <SECRET> via <SECRET_FILE>: <path> does not exist	The path in the SECRET_FILE environment variable doesn't exist. Confirm the path is accessible to the container running Retool.
RETOOL-CONFIG: Error setting <SECRET> via <SECRET_FILE>: <path> is a directory	The path exists but points at a directory rather than a file. Point it at the file itself.

Refer to Read secrets from the file system for the full configuration.

Why did Source Control stop syncing after an upgrade?

For React-based apps, Source Control depends on two storage backends that are health-checked independently of the api service: git storage and snapshots storage. Both appear in the container logs as RR git storage health check failed and RR snapshots storage health check failed.

Check that the configured blob storage is reachable and that credentials are still valid. Refer to Architecture for what each backend stores.

For classic apps, check the jobs-runner container logs instead. Refer to Troubleshooting Source Control for the log terms to search for and the rest of the sync troubleshooting flow.

Why did an upgrade leave the instance in a bad state?

Most upgrade failures come from services moving to different versions, or from a database migration that didn't complete.

1. Confirm every service is on the same version. A partial upgrade leaves services on mismatched versions, which surfaces first as the code-executor version mismatch described above.
2. Check migration logs. Retool runs database migrations on startup. A migration that fails leaves the schema partly applied, and the api service logs the failure.
3. Confirm you didn't skip a required version. Some releases must be applied in sequence. Refer to Upgrade Retool for the supported paths.

Before upgrading, take a database backup. Refer to Backup and recovery and Upgrade planning.

Why does the platform database keep growing?

The platform database accumulates data for every app version, query run, and audit log entry, so steady growth over time is expected. Left unmanaged, it can grow large enough to strain storage and backup windows.

• Check which tables are largest. App and page version history, query execution logs, and audit logs are the usual drivers of growth on long-running instances.
• Review your retention settings. Retool doesn't prune this data automatically by default; if you need to cap growth, configure retention for the data types generating the most volume instead of deleting rows manually.
• Run routine PostgreSQL maintenance. A database that's grown but never been vacuumed can appear larger on disk than the data it holds. Confirm autovacuum is enabled on your PostgreSQL instance.

This applies to the platform database itself, not resources you've connected. Refer to Configure and migrate to an external platform database for the database's architecture and requirements, and to Capacity planning for sizing guidance.

Why does HTTPS fail to configure on a new installation?

Docker Compose deployments provision HTTPS through https-portal, and most first-time failures come from DNS or port availability.

• Confirm DNS resolves before requesting a certificate. Let's Encrypt validates domain ownership by reaching your server over HTTP. A DOMAINS value in docker.env that doesn't yet resolve to the server fails to issue a certificate.
• Confirm port 80 is open and reachable. The https-portal requires it for the Let's Encrypt validation request, in addition to port 443. A firewall or security group blocking port 80 fails silently from Retool's side, since the failure happens during the provider's validation step.
• Confirm STAGE is set to production in compose.yaml. Left on the default staging value, https-portal issues a certificate browsers don't trust, which looks like an SSL failure rather than a configuration issue.
• For manually supplied certificates, confirm the certificate and key are mounted at the paths Retool expects, and that the certificate chain is complete rather than missing an intermediate.

Refer to Configure SSL and custom certificates for the full setup for both Let's Encrypt and manually managed certificates.

Why is the instance slow under load?

Slowness in a self-managed instance is usually resource starvation rather than a Retool defect.

1. Check pod resource limits. Pods being CPU-throttled or OOM-killed show up as latency and restarts rather than errors.
2. Check database connections. A saturated connection pool queues queries even while the database is healthy.
3. Check whether the right services are scaled. The api, jobs-runner, and workflows-worker services scale independently, and the bottleneck is often only one of them.

Refer to Scale Retool infrastructure and Capacity planning.

For slowness in a specific app rather than across the instance, refer to Troubleshooting apps.