Troubleshoot an Enterprise deployment
Use container state to locate the failure, then read that service's log. The API starts only after its database, license, migrations, and session connection are ready.
docker compose ps
docker compose logs --tail=100 api mysql redis-sessions redis-cache
Nginx does not have a health check in the supplied configuration. Its running state and a successful HTTP request establish that entry point separately.
Images do not download
| Error or symptom | What to verify |
|---|---|
| Registry authentication fails | The setup email's registry username and credential |
| Requested image is absent | IMAGE_TAG and access to the private application repositories |
| MySQL or Redis pull fails | The vendor image tag and Docker host access to its registry |
| Name resolution or connection timeout | DNS and outbound access from the Docker host |
start.sh logs in to registry.digidib.dev before it pulls images. It stops on a failed command.
If the supplied credential is rejected, send the registry error and image reference to Enterprise support.
The credential itself is not needed in the support message.
A service stays unhealthy
The startup dependencies are:
- MySQL, Redis sessions, and Redis cache become healthy.
- The API starts and becomes healthy.
- Server rendering and previews start after the API.
- Nginx starts after the API and server rendering.
For an API failure, inspect its log before restarting the other services.
A database connection error points to MySQL credentials, the service hostname, or the network.
A Redis connection error identifies either redis-sessions or redis-cache.
Changing MYSQL_PASSWORD or MYSQL_ROOT_PASSWORD in .env does not change accounts in an existing MySQL data directory.
Use the existing database password or rotate the MySQL account and application configuration together.
License validation fails
| Log message | Meaning and next step |
|---|---|
Unable to fingerprint machine, try again later. | Online activation failed. Read the preceding error for the license response or network failure. |
Mounted license file is invalid or expired and must be regenerated. | The supplied file failed validation. Verify the file, license key, expiry, and host fingerprint. |
Mounted license file is not permitted for air-gapped validation. | The file lacks the required offline entitlement. Obtain the correct license material. |
License Validation Error. Please contact contact@regex101.com! | Online license validation failed. Include the preceding response code in the support request. |
For a mounted file, verify that LICENSE_FILE points to the actual host file.
Verify that the license-file Compose override is active.
See Offline installations for the fingerprint command and mount behavior.
Database migrations fail
The API log contains Starting database migrations before it runs the migration files.
A successful run ends with Database migrations completed.
Timed out waiting for the database migration lock means another connection held the migration lock for the 60-second wait.
Verify that another API instance or migration process is not using the same database.
For a SQL error, read the failed statement and database error in the log. Preserve the database before changing tables manually. A partially applied MySQL schema change can remain after a failed migration.
If you need to return to the previous release, restore its database and image together with the database procedure.
The site does not open
Verify the local Nginx route from the Docker host. Replace the hostname with DOMAIN_NAME:
curl -I -H 'Host: regex101.example.com' http://127.0.0.1/
docker compose logs --tail=100 nginx ssr
If Nginx is published on a different host port, use that port in the command. A successful local response with a failed public URL points to DNS, the TLS proxy, or its upstream route.
The supplied Nginx configuration listens on HTTP port 80. Its published port 443 has no TLS listener. Configure HTTPS at your reverse proxy or load balancer.
Sign-in is missing or fails
A provider appears only when its required values are complete. Verify the provider's client ID, secret, and OAUTH_ORIGIN.
For custom OpenID Connect, also verify OAUTH_CUSTOM_ISSUER.
The registered callback URL must match the public origin and provider path exactly. Custom discovery must return the same issuer, including its path and trailing slash.
| Symptom | What to inspect |
|---|---|
| Provider button is absent | Required environment values and whether the application services were recreated |
| Redirect URI error | Registered callback URL versus OAUTH_ORIGIN |
| Custom discovery issuer error | The configured issuer versus the discovery response |
| Sign-in returns to a signed-out page | Public HTTPS origin, cookie domain, and proxy configuration |
| An existing user's workspace history is absent | Selected provider and any change to the custom issuer or subject identifier |
Use the OAuth guide for callback paths, scopes, and account identity.
A feature is unavailable
Feature access combines the installation's license entitlements and DISABLED_FEATURES.
A public Pro subscription does not add Enterprise license features.
Verify the installed license scope and any disabled feature IDs. For account-owned workspaces and integrations, also verify the signed-in account and operation permissions.
Send a support report
Send the application image reference, failing command or action, container state, and relevant error excerpt to contact@regex101.com. Include the MySQL image version for database errors and the provider type for sign-in errors. Remove secrets and workspace content from the excerpt before sending it.